The quote. Seven 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 request was understood and refused. Two codes reach this status.

VALIDATION_FAILED is the ordinary validator refusal, with a field map under errors.

INVALID_CURRENCY means the source currency passed validation and still cannot be priced. Its message names the currency and its errors.error is a bare string, not an array of strings — the same string as message.

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.

The quote could not be calculated.

The code you should expect is CONVERSION_QUOTE_ERROR, and its message is the fixed string below; the real cause is logged on our side and is not returned. This operation does not produce SYSTEM_DATABASE_ERROR. It is not the only code that can reach a 500 here, so switch on the code you got rather than assuming this one.

A 500 here is not a signal to change your request. Retry once, then escalate rather than looping.