Errors

Errors use one envelope across the API:

{
  "error": {
    "type": "ForbiddenError",
    "title": "Forbidden",
    "detail": "The transcriptions.read scope is required.",
    "code": "INSUFFICIENT_SCOPE",
    "request_id": "req_9bfbe80ac1f24e0a9d5b1e5e7a0f2c11"
  }
}

Branch on code

code is the stable, machine-readable field. It does not change with wording, translation or refactoring.

title and detail are human text and may be reworded between releases. type is the error class and is stable, but coarser than code — several codes share one class. Never parse detail.

Quote request_id when contacting support: it identifies the exact request in our logs.

Codes

HTTP	code	Meaning
400	INVALID_LIMIT	Page size outside 1–100.
400	INVALID_DATETIME	A timestamp is not RFC 3339 with an explicit offset.
400	INVALID_FILTER	A filter value or combination is unsupported.
400	INVALID_CURSOR	The cursor was edited, or the filters changed mid-traversal.
400	INVALID_REQUEST	Request validation failed, including unknown query parameters.
401	MISSING_ACCESS_TOKEN	No bearer token was sent.
401	INVALID_ACCESS_TOKEN	The token is invalid, expired, or its credential was revoked.
403	INSUFFICIENT_SCOPE	The token does not carry the scope the route requires.
403	API_ACCESS_DISABLED	The company does not have API access enabled.
404	RESOURCE_NOT_FOUND	Absent, owned by another company, or addressed in the wrong collection.
413	PAYLOAD_TOO_LARGE	The request body exceeds the accepted size.
415	UNSUPPORTED_MEDIA_TYPE	Wrong content type — most often JSON sent to /oauth/token.
429	RATE_LIMIT_EXCEEDED	A rate-limit policy rejected the request.
503	SERVICE_UNAVAILABLE	A fail-closed dependency is unavailable. Retry with backoff.
503	AUDIT_UNAVAILABLE	A successful read could not be recorded in the audit trail, so it was not returned.

Unknown identifiers are always 404

An id belonging to another company returns 404 RESOURCE_NOT_FOUND, not 403. The API does not confirm that a resource exists somewhere else — a 403 would leak that fact to anyone probing ids.

The token endpoint is different

POST /oauth/token returns the OAuth 2.0 error shape that RFC 6749 §5.2 mandates, so standard OAuth clients keep working:

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

What is never in an error

Stack traces, source paths, tokens, secrets, request bodies and domain payloads are never returned. An unexpected failure returns a fixed generic message with a request_id; the detail stays in our logs.

Retrying

Status	Retry?
400, 403, 404, 413, 415	No. The request will fail identically.
401	Once, after re-issuing the token.
429	Yes, after Retry-After.
503	Yes, with exponential backoff and jitter.