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` in your logs 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've 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.