Error Handling
- Retry?
Follow the supplied delay and retry guidance.
- Correlate
Keep the error and trace identifiers.
- Report
Include the failing request and time window.
You can decide the next client action and collect a useful support report.
Next: Error catalog
Your clients are getting errors. This page tells you when to retry, how to correlate failures across systems, and what to include when reporting issues.
Every error includes an id, code, kind, and optional retry hint — the same fields regardless of channel. The full field spec and all 16 error kinds are in the Error Contract reference. For the complete list of error codes, see the Error Catalog.
Retry guidance
Section titled “Retry guidance”When to retry
Section titled “When to retry”Without a retry delay, retry only the transient kinds:
RESOURCE_EXHAUSTED(rate limiting)DEADLINE_EXCEEDED(timeout)UNAVAILABLE(service unavailable)
The number of attempts is your client’s policy; Scribe does not prescribe one.
Retry strategy
Section titled “Retry strategy”if error.retry.after:
wait(error.retry.after)
retry()
elif response.header("Retry-After"):
wait(response.header("Retry-After"))
retry()
elif error.kind in [RESOURCE_EXHAUSTED, DEADLINE_EXCEEDED, UNAVAILABLE]:
wait(exponential_backoff())
retry()
else:
fail_permanently()Do not retry
Section titled “Do not retry”All other error kinds (13 of 16) should not be retried:
CANCELLED— client-initiated cancellationINVALID_ARGUMENT,OUT_OF_RANGE,FAILED_PRECONDITION— fix the requestUNAUTHENTICATED— re-authenticatePERMISSION_DENIED— request accessNOT_FOUND— resource doesn’t existALREADY_EXISTS,CONFLICT— resolve the conflictUNIMPLEMENTED— feature not availableINTERNAL,DATA_LOSS,UNKNOWN— contact support
Correlating errors
Section titled “Correlating errors”When logging errors, include these fields:
| Error field | Log key | Purpose |
|---|---|---|
id | error_id | Match with server logs and support tickets |
code | error_code | Aggregate errors by type |
kind | error_kind | Aggregate by category |
correlation | correlation_id | Trace across services |
trace_id | trace_id | Jump to the distributed trace |
{
”error_id": "550e8400-e29b-41d4-a716-446655440000",
"level": "ERROR",
"message": "Request failed",
"error_code": "DIRECTORY_BUSY",
"error_kind": "UNAVAILABLE",
"correlation_id": "req-12345",
"trace_id”: "0af7651916cd43dd8448eb211c80319c"
}