Handle errors and rate limits

This guide lists every error the Qualia API returns and what to do about each one. It also covers the rate limit, what happens when you run out of credits, and a safe retry policy.

Error format

Every error response has the same JSON body:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Validation failed: email: Invalid email address",
    "requestId": "req_x2f9kq7wz1mv8c3jtr0hbnyd"
  }
}

Field	Description
`code`	A stable identifier for the error. Branch on this or on the HTTP status.
`message`	A human-readable explanation. It can change, so do not parse it.
`requestId`	A unique ID for the request. Include it when you contact support.

Error codes

HTTP status	`code`	Cause	What to do
`400`	`bad_request`	The body is not valid JSON, or it contains a number too large to represent, such as `1e400`.	Send a JSON object and set `Content-Type: application/json`.
`401`	`unauthorized`	The `Authorization` header is missing or malformed, or the API key is wrong or revoked.	Send `Authorization: Bearer qk_live_...` with an active key. See Manage API keys.
`402`	`payment_required`	Your organization is out of briefing credits. Qualia did not record the signup.	Add credits in Settings → Billing, then send the signup again.
`404`	`not_found`	No actor with this ID exists in your organization, or no endpoint matches the path.	Check the `actorId` and the path. Actors from other organizations also return `404`.
`405`	`method_not_allowed`	The endpoint does not support the HTTP method, such as `DELETE /v1/actors`.	Use a method listed in the `Allow` header.
`413`	`payload_too_large`	The request body is larger than 1 MB.	Send one signup per request and trim `metadata`.
`422`	`unprocessable_entity`	The body failed validation. `message` names the field, for example `Validation failed: email: Invalid email address`.	Fix the named field. See Create an actor for the rules.
`429`	`too_many_requests`	This API key sent more than 60 requests in a minute.	Wait for the number of seconds in the `Retry-After` header, then retry.
`500`	`internal_server_error`	Something went wrong on Qualia's side.	Retry with backoff. If it keeps happening, contact support with the `requestId`.

Qualia may add new error codes. Handle unknown codes by falling back to the HTTP status.

Rate limits

Each API key can make 60 requests per minute. The limit covers POST /v1/actors and GET /v1/actors/{actorId} together. GET /v1/ping does not count toward it.

Successful responses from the actor endpoints, and 429 responses, include these headers:

Header	Description
`X-RateLimit-Limit`	Requests allowed per window.
`X-RateLimit-Remaining`	Requests left in the current window.
`X-RateLimit-Reset`	When the window resets, as a Unix timestamp in seconds.
`Retry-After`	On `429` only. Seconds to wait before you retry.

A 429 response looks like this:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790690580

{"error":{"code":"too_many_requests","message":"Rate limit exceeded.","requestId":"req_m4d1s8x0qa2vk7nwe9tplcjh"}}

To stay under the limit, watch X-RateLimit-Remaining and slow down as it nears zero. When you send many signups at once, such as a backfill, space them about one second apart. If you need a higher limit, contact support. We can raise the limit for a specific API key.

Out of credits

Each briefing uses one credit. When your balance is empty, every POST /v1/actors request returns 402 with code payment_required, including requests for emails Qualia already has. Qualia does not record the signup. Keep the signups you could not send, add credits, then send them again.

GET requests keep working and use no credits. See Credits for the full rules.

Retry policy

Response	Retry?	How
`429`	Yes	Wait for `Retry-After` seconds, then retry.
`500` or another `5xx`	Yes	Back off exponentially, for example 1, 2, then 4 seconds. Stop after a few attempts.
Network error or timeout	Yes	Same as `5xx`.
`402`	After you add credits	Queue the signup and send it again later.
`400`, `401`, `404`, `405`, `413`, `422`	No	Fix the request first. Retrying the same request gets the same error.

Retrying POST /v1/actors is always safe. Each email maps to one actor, so a retry never creates a duplicate or uses an extra credit.

For a ready-made retry helper, see SDK errors, retries, and timeouts.

Contact support

Email hello@qualia.so. Include the requestId from the error, or the actor ID if your question is about a signup.

Next steps

SDK errors, retries, and timeouts. How the SDK reports these errors, with retry code.
API overview. Authentication, limits, and versioning in one place.