API errors#

Every API failure uses one envelope. Branch on error.code, not message text.

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter.",
    "param": "sql",
    "doc_url": "https://api.supernova.ai/docs#parameter_missing",
    "request_id": "req_..."
  }
}

The Request-Id response header repeats request_id. Include it when contacting support. param appears only when one input can be named.

Status classes#

Status	Meaning	Retry
`400`	Invalid input or refused capability	Change the request
`401`	Missing, malformed, expired, or revoked credential	Refresh or replace the credential
`403`	Authenticated but missing scope or role	Request appropriate access
`404`	Resource absent or hidden from this organization	Do not infer cross-tenant existence
`409`	Current state conflicts with the operation	Read current state, then decide
`429`	Caller, organization, or concurrency limit	Honor `Retry-After`
`500`	Unexpected server failure	Retry with backoff when the request is idempotent
`503`	Required service unavailable	Retry with backoff

Common codes#

Code	Meaning
`invalid_json`	Body is not valid JSON
`parameter_missing`	Required input is absent
`invalid_cursor`	Cursor did not come from the matching collection
`invalid_format`	Requested representation is unsupported
`authentication_required`	Bearer credential is absent
`invalid_token`	Credential failed validation
`insufficient_scope`	Credential lacks the endpoint scope
`rate_limited`	Request rate exceeded
`idempotency_key_reused`	Key was bound to different input
`query_not_found`	Query is unavailable to this organization
`job_not_found`	Job is unavailable to this organization
`catalog_not_found`	Schema or table is absent or hidden
`source_not_found`	Source is absent or hidden
`send_not_found`	Send or nested run is absent or hidden

Resource pages list their additional codes at the operation that returns them.