Errors

Error fields, status codes, causes, and recovery actions.

A failed request returns an HTTP status and a JSON error object. Use the machine-readable code for application behavior and the request ID for diagnosis.

Error envelope

409 Conflict

{
  "error": {
    "code": "collection_not_ready",
    "message": "No file in the collection is ready yet. Try again.",
    "request_id": "req_example_not_ready",
    "retryable": true,
    "details": {
      "retry_after_seconds": 15
    }
  }
}

Field	Type	Meaning
`error`	object	The error envelope.
`error.code`	string	Stable machine-readable reason for the failure.
`error.message`	string	Human-readable explanation. Do not parse this text for program logic.
`error.request_id`	string	The Engine request ID of this failed request. It equals the x-engine-request-id header. It is not your X-Request-Id.
`error.retryable`	boolean	Whether another attempt can succeed without correcting the underlying request.
`error.details`	object of JSON values	Additional context, such as retry_after_seconds, a field, or a limit. Can be empty.

Status and code catalog

HTTP	Code	Cause	What to do
400	`invalid_request`	A request field, body, or query is invalid.	Correct the request using the endpoint schema. Unknown fields are rejected.
400	`invalid_cursor`	The cursor expired or does not belong to this request.	Restart from the first page with the intended request and key.
400	`invalid_uri`	The source URI is invalid or its scheme is unsupported.	Check URI syntax and storage.schemes from /info.
400	`invalid_filter`	A filter uses an invalid field, operator, or value.	Check error.details and the supported filter grammar.
400	`invalid_span`	A span in a Read spans body has a bad shape, such as a `pages` span that starts at 0.	Send each span as Search, Answer, or Research returned it. Pages count from 1.
401	`unauthenticated`	No valid API key was supplied.	Send a valid key. Replace a revoked or incorrect secret.
403	`forbidden`	The visible resource is outside the key’s allowed actions.	Use a key with the required action.
404	`not_found`	The resource is missing or outside the key’s resource scope.	Check both the identifier and the key’s namespace or collection scope.
409	`already_exists`	A unique resource name conflicts.	Use exist_ok where supported, or choose another name.
409	`idempotency_conflict`	An idempotency key was reused with a different body.	Retry with the original body or use a new key for a new operation.
409	`collection_empty`	Answer or Research has no files to use.	Add content and wait until it is ready.
409	`collection_not_ready`	No content is ready for the requested retrieval.	Wait for processing, or correct failed files when retryable is false.
409	`operation_in_progress`	Another operation conflicts with this write.	Wait for its job to finish before submitting another operation.
409	`limit_exceeded`	A resource or request value exceeds a size limit.	Reduce the value or resource count described by the error.
409	`external_source`	Engine cannot provide a download URL for this source.	Retrieve original bytes through your authorized storage service.
409	`webhook_disabled`	The webhook is disabled, so Replay cannot queue events.	Enable it with Update webhook, then retry.
413	`request_too_large`	The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.	Reduce the body or use an upload or supported URI for file content.
422	`storage_unreachable`	The cluster cannot read the source object.	Check object existence and the cluster’s storage access.
429	`rate_limited`	The cluster rejected request volume.	Delay retries and reduce concurrent requests.
500	`internal_error`	An unexpected server failure occurred.	Retain request_id for diagnosis. Recover current state before repeating a write.
503	`temporarily_unavailable`	Required capacity or a dependency is unavailable.	Honor retry guidance and retry with the same idempotency key when applicable.

Operation pages list the errors relevant to that request. Scope errors can occur before resource validation. A namespace key receives 404 for another namespace, and a collection key receives 404 for an unnamed collection.

Read spans reports a problem with one span in error on that span’s result, not as an HTTP error, and the other spans still read. The codes are not_found, invalid_span (the span does not fit the file), and content_unavailable (the stored content is missing or cannot be read, and a retry gets the same answer). Read another span, or add the file again.

Retry and recover

Inspect retryable and any retry_after_seconds in details. Fix invalid parameters and insufficient permissions before retrying. Wait for completion events when a collection or job is still processing.

A network timeout does not prove a write failed. For an operation that requires idempotency, retry the same body with the same Idempotency-Key. For accepted work, retain the job ID and recover its state with one GET.

Use a bounded retry policy for transient failures. Keep the request ID when reporting a problem. The pagination and idempotency contract explains replay behavior.

Failures after acceptance

An operation can fail after a 202 response. The failure then appears in the job’s error and can appear in the file’s error. Receive events, then read the resource for its current failure details.

An empty Search result is not always an error. Check warnings to distinguish no matches from a collection whose files failed. Answer on an empty collection returns collection_empty.

Was this page helpful?

View as Markdown