Docs Sign inGet started
API reference

Errors

Onym uses standard HTTP status codes and returns one error object with a stable code.

Ask Claude Ask ChatGPT
Error
{
  "error": {
    "type": "invalid_request_error",
    "code": "domain_not_found",
    "message": "No such domain in this workspace. List them with GET /domains.",
    "param": "domain",
    "doc_url": "https://getonym.com/docs/api/errors#domain_not_found"
  }
}

The error object

Field Description
type The broad category, below
code A stable, machine-readable code. Handle errors by code, not by message
message A sentence for people. It may change
param The parameter at fault, or null
doc_url A link to this page, at the code

Every response also has an X-Request-Id header, like req_3f9c2a1e6b7d4e8f. Include it when you contact support.

Status codes

Status Meaning
200 It worked
201 It worked and created something
400 A parameter is invalid
401 No key, or the key is invalid or expired
403 The key or plan doesn't allow this
404 The domain, prompt, answer or dataset doesn't exist in this workspace
429 Too many requests. Wait for Retry-After seconds
5xx Something went wrong on our side. These are rare; retry with backoff

Error types

type Statuses
authentication_error 401
permission_error 403
invalid_request_error 400, 404
rate_limit_error 429
api_error 5xx

Error codes

code Status What to do
missing_api_key 401 Send Authorization: Bearer onym_...
invalid_api_key 401 Check the key, or create a new one
token_expired 401 Refresh the OAuth access token
read_only_key 403 Use a write key
plan_required 403 Custom prompts need a paid plan
domain_not_found 404 List domains with GET /domains
prompt_not_found 404 The prompt has no answers in this range, or doesn't exist
answer_not_found 404 Check the answer ID
dataset_not_found 404 Use visibility, prompts, sources or answers
invalid_parameter 400 Fix the parameter named in param
rate_limited 429 Wait Retry-After seconds