Errors, limits and retry behavior

Inspect both the HTTP status and JSON response. Most controller errors use success: false and message; validation failures may also contain an errors object keyed by request field. Laravel validation responses and Autopilot resources do not always include success.

Status Meaning What to do
400 Input cannot be processed, including generator token-size limits Reduce source input and retry the corrected request
401 Missing or invalid authentication Check the account token and Bearer header
403 Access, plan, credit or feature restriction Read the message; confirm account permissions and entitlement
404 Resource absent, inaccessible in this lookup, or document belongs to another Space Re-list resources and check numeric IDs
405 Wrong HTTP method Follow the endpoint's GET/POST/PUT/PATCH/DELETE contract
409 Autopilot suggestion is stale Re-read the current page and suggestion before applying
422 Validation or an unsupported action/state Correct fields using errors or message
429 Request throttled by the serving environment Honor Retry-After when supplied and reduce request frequency
500 / 502 Application or upstream failure Preserve request context, retry reads with backoff, contact support if persistent

Validation example

{"success":false,"message":"Validation failed","errors":{"title":["The title field is required."]}}

The exact message text can vary. Branch on status and field names, not English wording.

Avoid duplicate work

The documented create and generate endpoints do not expose an idempotency-key contract. After a timeout, the server may already have completed the operation. Check generation history or document lists before repeating a mutation. Retrying a generator may create another generation and consume additional credits. Generator requests run synchronously; allow a suitable client timeout instead of assuming an immediate job ID.

Pagination, input bounds and feature gates differ by endpoint. This reference does not promise a universal requests-per-minute allowance. Use the per-endpoint constraints and your current account entitlement. Never interpret an empty search result as proof that a document does not exist: recently edited content can still be indexing.

Updated