Skip to content

Error Contract

  • Identity

    Keep the error identifier and code.

  • Action

    Read the error kind and available retry hint.

  • Format

    Check which fields your API returns.

Each API carries error information in its own response format.

Find exact fields and channel formats for your client’s error handling.

Next: Error codes

Every channel reports a failure with the same id and code. REST and GraphQL carry the fields below except details; LDAP and MCP carry fewer fields in their own formats, as Per-channel formats shows.

For the full list of error codes and their details schemas, see the generated Error Catalog. For retry strategy and error correlation, see Error Handling.

FieldStabilityDescription
idStableUnique failure identifier (UUID)
timestampStableWhen the failure occurred (ISO 8601)
codeStableMachine-readable error code (e.g., ARGUMENT_INVALID_JSON)
kindStableError classification (e.g., INVALID_ARGUMENT)
messageInformationalHuman-readable description — may change between versions, do not parse
trace_idStableOpenTelemetry trace ID (optional, when tracing is active)
span_idStableOpenTelemetry span ID (optional)
correlationStableRequest correlation ID (optional, when client provides one)
retryStableRetry hint: { "after": "PT2S" } — absent when retry is not suggested
detailsStableStructured context specific to the error code (optional). Recorded in logs for diagnostics; never sent to clients

Backwards compatibility: details schemas may gain new optional fields, but existing fields are never removed or renamed.

Default codes: When no explicit code is set, the code defaults to the kind name (e.g., INVALID_ARGUMENT). See the Error Catalog for all codes.

Scribe uses 16 error kinds, aligned with gRPC status codes:

KindMeaningDefault Retry
CANCELLEDCaller cancelled the operationNever
INVALID_ARGUMENTBad request parametersNever
OUT_OF_RANGEValue out of rangeNever
FAILED_PRECONDITIONWrong system stateNever
UNAUTHENTICATEDMissing or invalid credentialsNever
PERMISSION_DENIEDCaller lacks permissionNever
NOT_FOUNDResource not foundNever
ALREADY_EXISTSResource already existsNever
CONFLICTConflicts with current stateNever
RESOURCE_EXHAUSTEDQuota or capacity exceededAfter 2s
DEADLINE_EXCEEDEDOperation timed outAfter 1s
UNAVAILABLEService temporarily unavailableAfter 5s
UNIMPLEMENTEDOperation not supportedNever
INTERNALInternal error (invariant broken)Never
DATA_LOSSUnrecoverable data corruptionNever
UNKNOWNUnknown or unmapped errorNever
PER CHANNELOne failureid · code · kindRESTerror body + Error-IdGraphQLerrors[].extensionsLDAPresult + code, idMCPerror tool resultid + code
PER CHANNELOne failureid · code · kindRESTerror body + Error-IdGraphQLerrors[].extensionsLDAPresult + code, idMCPerror tool resultid + code
Each channel carries the same failure identity in its own response format.
ChannelWhere to find the error
HTTP/RESTJSON body under error + response headers (Error-Id, Error-Code, Error-Kind, Retry-After)
GraphQLerrors[].message, with the other fields except details in errors[].extensions, plus a standard graphqlCode
LDAPResult code (for example busy for DIRECTORY_BUSY) + diagnostic message ending in JSON with id and code only
MCPTool result marked as an error, listing code, kind, ID and retry hint as Markdown

In a REST error body, client code decides on kind and code, never on message:

"kind": "UNAVAILABLE",
"code": "DIRECTORY_BUSY",
"message": "Directory service is busy."

REST example:

HTTP/1.1 503 Service Unavailable
Error-Id: 7c9e6679-7425-40de-944b-e07fc1f90ae7
Error-Code: DIRECTORY_BUSY
Retry-After: 2
{
"error": {
"id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"code": "DIRECTORY_BUSY",
"kind": "UNAVAILABLE",
"message": "Directory service is busy. Please retry later.",
"status": 503,
"retry": { "after": "PT2S" }
}
}

For full transport details (status code mappings and header formats), see the REST, GraphQL, LDAP, and MCP channel docs.

Note: Some details fields (configuredBases, baseTypes, value, filter) may contain sensitive information. Deployments can omit these fields depending on their exposure policy. Clients should handle missing details gracefully.