⚠️ Errors & Status Codes

The API uses standard HTTP status codes. A 2xx means success. Anything else carries a JSON body describing what went wrong.

Error shape

Failed requests return an error object, never a bare string:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized",
    "docs": "https://compass.mesa.so/docs/api"
  }
}

Branch on code, not on message. The code is a stable identifier; the message is prose we may reword. docs is on every error.

Two codes carry extra fields:

401 adds baseUrl and hint, naming the host to call. If you are reading this because a call returned HTML instead of JSON, that is the fix: send requests to https://api.compass.mesa.so, not to the website.
402 adds required (credits this call needed), balance (what you hold), and resolve.upgradeUrl / resolve.creditsUrl, so an agent can react without parsing the sentence.

Read the status code first to decide how to react, then read code for detail.

Code	Meaning	What to do
`200`	Success	Read the data in the response body.
`400`	Bad request	Your input failed validation. Fix the request and resend.
`401`	Unauthorized	The key is missing, malformed, or revoked. Check the `Authorization` header and that the key is active.
`402`	Payment required	You are out of credits. Add credits by starting or upgrading a plan (or earn them via referrals or email/telegram verification), then retry. See Pricing & Quotas.
`403`	Forbidden	The key is valid but lacks the scope for this resource (for example `read:contacts` for a private reveal).
`404`	Not found	The resource does not exist, is not visible to your account, or the path is not an endpoint. An unrecognised path names itself in `message` and points you at `/v1/me`, which lists every endpoint that does exist.
`409`	Conflict	The request clashes with current state, such as creating one key too many.
`429`	Too many requests	You hit the rate limit. Back off and retry. See Access & Rate Limits.
`5xx`	Server error	Something failed on our side. Retry after a short wait; if it persists, get in touch.

Check the status before the body. It tells you whether to read data or an error.
Treat 401 as a key problem. Confirm the header reads Authorization: Bearer ck_live_… and the key is active in your API tab.
Treat 402 as a credits problem. You ran out of credits. Subscribe or upgrade, then retry. Automated agents should prompt their owner to top up. See For AI Agents.
Retry 429 and 5xx with backoff. Wait and retry rather than resending immediately.
Do not retry 400 unchanged. A bad request will fail the same way until you fix the input.