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.
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.
Fields
Section titled “Fields”| Field | Stability | Description |
|---|---|---|
id | Stable | Unique failure identifier (UUID) |
timestamp | Stable | When the failure occurred (ISO 8601) |
code | Stable | Machine-readable error code (e.g., ARGUMENT_INVALID_JSON) |
kind | Stable | Error classification (e.g., INVALID_ARGUMENT) |
message | Informational | Human-readable description — may change between versions, do not parse |
trace_id | Stable | OpenTelemetry trace ID (optional, when tracing is active) |
span_id | Stable | OpenTelemetry span ID (optional) |
correlation | Stable | Request correlation ID (optional, when client provides one) |
retry | Stable | Retry hint: { "after": "PT2S" } — absent when retry is not suggested |
details | Stable | Structured 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:
| Kind | Meaning | Default Retry |
|---|---|---|
CANCELLED | Caller cancelled the operation | Never |
INVALID_ARGUMENT | Bad request parameters | Never |
OUT_OF_RANGE | Value out of range | Never |
FAILED_PRECONDITION | Wrong system state | Never |
UNAUTHENTICATED | Missing or invalid credentials | Never |
PERMISSION_DENIED | Caller lacks permission | Never |
NOT_FOUND | Resource not found | Never |
ALREADY_EXISTS | Resource already exists | Never |
CONFLICT | Conflicts with current state | Never |
RESOURCE_EXHAUSTED | Quota or capacity exceeded | After 2s |
DEADLINE_EXCEEDED | Operation timed out | After 1s |
UNAVAILABLE | Service temporarily unavailable | After 5s |
UNIMPLEMENTED | Operation not supported | Never |
INTERNAL | Internal error (invariant broken) | Never |
DATA_LOSS | Unrecoverable data corruption | Never |
UNKNOWN | Unknown or unmapped error | Never |
Per-channel formats
Section titled “Per-channel formats”| Channel | Where to find the error |
|---|---|
| HTTP/REST | JSON body under error + response headers (Error-Id, Error-Code, Error-Kind, Retry-After) |
| GraphQL | errors[].message, with the other fields except details in errors[].extensions, plus a standard graphqlCode |
| LDAP | Result code (for example busy for DIRECTORY_BUSY) + diagnostic message ending in JSON with id and code only |
| MCP | Tool 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 UnavailableError-Id: 7c9e6679-7425-40de-944b-e07fc1f90ae7Error-Code: DIRECTORY_BUSYRetry-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.