Errors

Plurall AI returns structured errors with a stable code and a human-readable message.

All Plurall AI errors share the shape { code, message, hint, request_id }. The code is the contract: your code should branch on it. The message is human-readable and may be reworded over time. Always log request_id so support can find the trace.

{
  "code": "auth.scope_missing",
  "message": "The bearer key does not have the cases:write scope.",
  "hint": "Issue a new key with the appropriate scopes.",
  "request_id": "req_a8b1c2"
}

Common error codes

auth.invalid_key
Your bearer key is missing, malformed, or revoked.
auth.scope_missing
The key is valid but lacks the required scope.
ingest.too_large
The file exceeds 2 GB.
ingest.unsupported_kind
The container is not in the supported list.
rate_limit.exceeded
You have crossed your plan's quota; back off using the Retry-After header.

Retry semantics

5xx errors are safe to retry. 4xx errors should not be retried: they indicate the client needs to change something. The exception is rate_limit.exceeded, which is retryable after Retry-After.