The endpoint was updated. Six keys.

The request carried no key, a key that could not be parsed, or a key that did not verify.

A 401 has two different body shapes, and which one you get depends on the layer that refused you, not on the status code.

Authentication runs in middleware, ahead of every controller, and that layer answers with error and code — no success, no message. All five middleware codes are listed below. It also runs before validation, so a request with no key and an invalid body comes back as a 401 rather than a 422.

Six operations — create, read and cancel on payment links, and the same three on card payments — can also return a 401 from inside the controller, in the ordinary {success, code, message} envelope with code: INVALID_API_KEY. That one means the key verified but its own record is incomplete: it carries no creating user, which is how these six reach your payment links. The fault is the key record, not the account, and the key has to be replaced. The same six pair it with 404 USER_NOT_FOUND — "User associated with API key not found" — for the case where that user existed and no longer does. The other ten operations cannot produce it.

Do not switch on the status code to decide which shape to parse. Test for the key you need: the middleware envelope has error, the ordinary envelope has success and message.

Two different refusals share this status, and neither uses the ordinary envelope.

insufficient_scope — the key is valid but does not carry the ability this operation requires. Abilities are matched exactly, except that a key holding * satisfies every one of them. It is only reachable on the twelve operations that declare an ability: the four reference operations declare none, so any valid key of the account reaches them.

ORIGIN_NOT_ALLOWED — the request's origin is not in the key's allowed list. It is reachable on every operation, and only when the key has a non-empty allowed-origins list; a key with none is never origin-checked.

Business refusals — a paused account, or card payments not being enabled — also answer 403, but in the ordinary {success, code, message} envelope, and are declared on the operations that raise them rather than here.

The code is WEBHOOK_NOT_FOUND. A malformed id never reaches this operation and answers RESOURCE_NOT_FOUND instead.

The request was understood and refused.

errors is optional, including on code: VALIDATION_FAILED. The field-by-field map is what a failed validator produces; other refusals carry the same code with a prose message and no errors key at all. Read message first and treat errors as extra detail when it is there.

When errors is present, its values are not always arrays of strings. A validator emits {"<field>": ["<message>", ...]}, but other 422s on this API put a single string or a single integer under a key of their own. Type the map's values as unknown and inspect before you index.

Several 422s carry no errors key: among them WALLET_NOT_FOUND, USD_ACCOUNT_NOT_ENABLED, EXCHANGE_RATE_UNAVAILABLE and WEBHOOK_ALREADY_EXISTS. The codes that can reach a given operation are listed on that operation.

Two independent limiters run on every operation, and they answer with different bodies, different codes and different headers.

By client IP — 100 requests per 60 seconds. This one runs before authentication, so unauthenticated requests count against it too, and every integrator behind the same egress IP shares one budget. Its refusal carries code: RATE_LIMIT_EXCEEDED, in the ordinary envelope plus a retry_after.

By API key — the key's own limit per 60 seconds, 60 when a key is minted and settable between 1 and 10000. Its refusal carries code: rate_limit_exceeded in the middleware envelope.

The two codes differ in case as well as in shape, and that is the only reliable way to tell which limiter refused you.

Both windows are fixed rather than rolling: the window opens with its first request and the counter resets wholesale when it expires. retry_after, in whole seconds, is on both bodies and is the value to back off on.

Only the IP limiter sets Retry-After. A 429 from the per-key limiter carries no Retry-After at all, so read retry_after from the body rather than the header.

A successful response carries four counters: X-RateLimit-Limit-IP and X-RateLimit-Remaining-IP for the IP limiter, X-RateLimit-Limit and X-RateLimit-Remaining for the key limiter. There is no reset header on either pair.

Something failed on our side, or in a system we depend on. The body is the ordinary {success, code, message} envelope.

Only code is contractual. message is not. The text on this path describes an internal failure, is not drawn from any documented set of strings, and can change without notice. Switch on code, keep the whole body in your logs if it helps you, and never parse message, match on it, or show it to a payer.

The shared code is SYSTEM_DATABASE_ERROR, reachable on fourteen of the sixteen operations. The two conversion operations cannot produce it and describe their own failure codes; the operations that can raise a second 500 code name it in their own description.

A 500 can also arrive with a code this reference does not list — today, SYSTEM_UNEXPECTED_ERROR. It is not part of the contract, its cause is not documented, and it is handled exactly like any other 500. Nothing is promised about when it fires.

A 500 is usually not a signal to change your request. Retry once, then escalate rather than looping — a 500 that keeps repeating is almost always ours to fix, not yours.

The "almost" is deliberate. A few inputs pass validation and then produce a 500 that only a change to the request will clear, and retrying those never helps: a currency field sent as a JSON array rather than a string, on card-payment create and on both conversion operations; a destination on POST /v1/conversions/quote that the operation cannot price, which is only checked for length; and amount_type on that same operation sent as null or "" instead of being omitted. None of those refusals is documented and no status is promised for them — send a three-letter string, send a currency you are credited in, and omit an optional field rather than emptying it.