Skip to content

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.

Use the retry hint, keep the error identifier, and escalate with context.

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.

Request failedRetry hint?retry.afterRetry-After?HTTP headerTransient kind?error.kindWait, then retrygiven delayBack off, retryexponentialDo not retryfix the causecheckyesnoyesnoyesno
Request failedRetry hint?retry.afterRetry-After?HTTP headerTransient kind?error.kindWait, then retrygiven delayBack off, retryexponentialDo not retryfix the causecheckyesnoyesnoyesno
Use an explicit retry delay first; otherwise retry only the transient error kinds, with exponential backoff.

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.

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()

All other error kinds (13 of 16) should not be retried:

  • CANCELLED — client-initiated cancellation
  • INVALID_ARGUMENT, OUT_OF_RANGE, FAILED_PRECONDITION — fix the request
  • UNAUTHENTICATED — re-authenticate
  • PERMISSION_DENIED — request access
  • NOT_FOUND — resource doesn’t exist
  • ALREADY_EXISTS, CONFLICT — resolve the conflict
  • UNIMPLEMENTED — feature not available
  • INTERNAL, DATA_LOSS, UNKNOWN — contact support
YOUR SIDESUPPORTError responseError-Id · Trace-IdYour client logerror_id · trace_idProcess outputincident windowSupport ticketServer logssame Error-IdTraceif tracing is onrecordError-Idlog windowmatchesopens
YOUR SIDESUPPORTError responseError-Id · Trace-IdYour client logerror_id · trace_idProcess outputincident windowSupport ticketServer logssame Error-IdTraceif tracing is onrecordError-Idlog windowmatchesopens
Keep the failure ID together with its timestamp and request evidence; support uses that ID to find the exact failure.

When logging errors, include these fields:

Error fieldLog keyPurpose
iderror_idMatch with server logs and support tickets
codeerror_codeAggregate errors by type
kinderror_kindAggregate by category
correlationcorrelation_idTrace across services
trace_idtrace_idJump 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"
}