Please take the OpenCensus user survey



Status defines a logical error model to represent a filterable state of the span at a point in time.

It consists of a code whose type is int32 as well as the descriptive message.

Status allows tracing visualization tools to highlight unsuccessful spans and helps in debugging errors.

Status code mapping

For a uniform mapping of status code in various RPC systems, we use the following enumerations alongside description to describe the state of the system in span, as per:

State Code Description HTTP status code equivalent
OK 0 Not an error, returned on success 200 and 2XX HTTP statuses
CANCELLED 1 The operation was cancelled, typically by the caller 499
UNKNOWN 2 An unknown error raised by APIs that don’t return enough error information 500
INVALID_ARGUMENT 3 The client specified an invalid argument 400
DEADLINE_EXCEEDED 4 The deadline expired before the operation could succeed 504
NOT_FOUND 5 Content was not found or request was denied for an entire class of users 404
ALREADY_EXISTS 6 The entity attempted to be created already exists 409
PERMISSION_DENIED 7 The caller doesn’t have permission to execute the specified operation 403
RESOURCE_EXHAUSTED 8 The resource has been exhausted e.g. per-user quota exhausted, file system out of space 429
FAILED_PRECONDITION 9 The client shouldn’t retry until the system state has been explicitly handled 400
ABORTED 10 The operation was aborted 409
OUT_OF_RANGE 11 The operation was attempted past the valid range e.g. seeking past the end of a file 400
UNIMPLEMENTED 12 The operation is not implemented or is not supported/enabled for this operation 501
INTERNAL 13 Some invariants expected by the underlying system have been broken. This code is reserved for serious errors 500
UNAVAILABLE 14 The service is currently available e.g. as a transient condition 503
DATA_LOSS 15 Unrecoverable data loss or corruption 500
UNAUTHENTICATED 16 The requester doesn’t have valid authentication credentials for the operation 401

Source code samples

span.SetStatus(trace.Status{Code: int32(trace.StatusCodeNotFound), Message: "Cache miss"})
span.setStatus(status.NOT_FOUND.withDescription("Cache miss"))
span.status = Status(5, "Cache miss")
span.SetStatus(StatusCode.NOT_FOUND, "Cache miss");
// Not implemented at this time


As you can see above, we set the status with a message of “Cache miss” and a code of NOT_FOUND


Resource URL
Status in OpenCensus datamodel proto/v1/Status
RPC code mappings Code enumerations rpc/code.proto
Go API Span.SetStatus
Java API Span.SetStatus
Python API Status
C++ API Span.SetStatus