Skip to main content
Errors use the same envelope as successful responses, with success: false:
Branch on error.code — it’s a fixed enum and stable. message is human-readable and may be reworded; details is optional.

The codes

There are twelve, and that’s the complete set:

The distinctions that matter

402 vs 429 — waiting only fixes one

USAGE_LIMIT_EXCEEDED (402) means a plan allowance is exhausted on a live plan. Waiting a minute changes nothing: a monthly allowance resets on the 1st of the month (UTC), and a held one — tracked keywords, AI prompts, local locations — only frees up when you remove something. Upgrading fixes it now. details carries the metric, limit, used and plan. The dashboard turns this code into its upgrade prompt, which is why it doesn’t share a code with rate limiting. PLAN_REQUIRED (402) means the organization has no live plan — its trial ended, or its subscription did. Everything already collected is still readable, but nothing billable runs until an admin or owner chooses a plan. There’s no bigger plan to suggest, which is why it’s a separate code from USAGE_LIMIT_EXCEEDED. RATE_LIMITED (429) means you’re going too fast. Waiting is the fix, and the response tells you how long — see Rate limits. Never retry a 402 on a short backoff, and never treat a 429 as a billing problem.

403 vs 404 — a deliberate asymmetry

NOT_FOUND is returned both for things that don’t exist and for things that exist but aren’t yours. A project id from another organization answers 404, never 403, because a 403 would confirm the id is real — which is the fact being protected. The same applies to organizations: if you’re not a member, you get “Organization not found.” FORBIDDEN is reserved for the case where you can already see the resource and simply can’t perform this action — a member doing an admin’s job, or an admin deleting the organization. The message names the role required, for example “This action requires the admin role.” So: a 404 doesn’t prove deletion. Check you’re using the right ids before concluding anything. An invitation you haven’t accepted also reads as 404. The membership row exists to hold the invitation, not to grant access.

502, not 503

An upstream failure — the SERP provider, the payment processor, the mail service — answers UPSTREAM_ERROR with a 502. It’s Surnex reporting someone else’s failure, and it’s usually worth retrying.

Retry policy

Job failures aren’t API errors

A background job that fails returns a successful response containing a job whose status is failed, with an error message attached. Check the job status, not just the HTTP status. See Jobs and polling.