Errors

The Graphon error shape, HTTP classes, error codes, and how to handle them.

Error shape

Every error returns the same JSON shape, on the API host and on the storage host. Graphon also sends x-request-id on every response. The OAuth routes under /oauth are the exception: they return the standard OAuth error, { "error": "invalid_request", "error_description": "…" }, because OAuth clients read that shape.

JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Choose a valid role.",
    "requestId": "8f0c2c4e-6b1a-4d2e-9a10-0d5f6a7b8c9d",
    "retryable": false
  }
}

Fields

code — a short, stable machine token.
message — human-readable text, when Graphon has one.
error.requestId — the same value as the x-request-id header.
retryable — true when the same request can work later with no change. false when the same request gets the same error: change the request, the key, or the bucket first. The flag belongs to the response, not to the code.
details — more about the error, when Graphon has more. A retryable error has details.retryAfterSeconds.

Retry an error

A retryable error also has a Retry-After header with the seconds to wait. details.retryAfterSeconds has the same value.

HTTP

HTTP/1.1 409 Conflict
Content-Type: application/json
Retry-After: 30
x-request-id: 6f1c2e0a-3b7d-4c91-8e2f-5a4d9b0c1e73

{
  "error": {
    "code": "index_not_ready",
    "message": "No object in this bucket is ready yet. Retry after 30 seconds.",
    "requestId": "6f1c2e0a-3b7d-4c91-8e2f-5a4d9b0c1e73",
    "retryable": true,
    "details": { "retryAfterSeconds": 30 }
  }
}

HTTP classes

Status	Meaning
`2xx`	The request succeeded.
`400`	The request body or query is invalid. A body field that the route does not take is invalid, and the message names it.
`401`	The API key is missing, invalid, expired, or revoked.
`403`	The key is valid but lacks the required role, or the request needs access that the workspace does not have.
`404`	The workspace or resource was not found.
`409`	The request conflicts with the current state, such as the last admin, or a bucket that is not ready.
`413`	The request body is too large. Most JSON routes take at most 16,384 bytes; see Limits for the routes that take more. A storage upload request can carry at most 200 MiB.
`500`	A Graphon error. Report the requestId.
`503`	A service that the request needs is busy or did not answer in time. Send the same request again after the Retry-After seconds.

Search and answer codes

Search objects, Read spans, Answer a question, and Start research add these codes. A target that is a draft, retired, or unknown dataset returns 404 not_found, like a bucket of another workspace. An empty bucket or dataset, or one whose content all failed to index, is not an error: search returns no results, and answer and research return no answer, each with the warning index_empty or index_failed.

Status	Code	Meaning
`400`	`invalid_cursor`	The cursor expired, or the body differs from the first page. Send the same body, or search again without a cursor.
`403`	`bucket_offline`	The bucket is offline. An editor can bring it online.
`403`	`dataset_access_required`	The target is a paid dataset, and the workspace has no access to it. details.target names the dataset. A workspace admin can get access.
`403`	`feature_not_in_plan`	Reserved. The workspace's plan lacks a premium feature that the request uses. details.feature names it. Today every workspace has every feature.
`409`	`bucket_not_ready`	The bucket is not active. retryable is true while the bucket is being created, and false when it failed to create.
`409`	`indexing_disabled`	The bucket does not index its objects, so it cannot be searched.
`409`	`index_not_ready`	No object in the bucket, or no document in the dataset, is ready yet. Retry after the Retry-After seconds.
`503`	`temporarily_unavailable`	Search did not answer in time or is busy, or Graphon cannot serve a dataset right now. Send the same request again.

Was this page helpful?

View as Markdown