Crypto Payment Gateway Error Codes 2026: We Mapped 9

Your checkout is returning a failure and the only thing you have is a response body. On the nine crypto payment gateways we track, that body is formatted nine different ways, and three of them will not even tell you which kind of failure it was — a wrong key, a wrong URL and a transient fault can all arrive wearing the same HTTP status. Crypto payment gateway error codes are the part of an integration nobody budgets for, and then a weekend goes into reverse-engineering them.

We spent 4 October 2026 doing exactly that, deliberately. We read every error reference these nine publish, then sent each one an identical malformed request and recorded the status, the headers and the bytes. Every figure below was captured from the live APIs on that date and every documented value was read from a first-party page, not from a comparison article. Here is what nine vocabularies for “your key is wrong” actually look like.

Which crypto payment gateways document their error codes

Five of the nine have a page you can point a new engineer at. The rest make you assemble the vocabulary yourself, out of example responses and endpoint pages,.

Gateway	Consolidated error reference	Error values published	Scheme
BitPay	Yes — Error Codes in the developer docs	26 code suffixes	6-digit numeric; method and resource encoded in the digits
Plisio	Yes — HTTP Response Status Codes appendix	16 statuses, 12 with named constants	Named constants, one per status
BlockBee	Yes — Error Handling guide	24 message strings	Plain-English strings, grouped by status
Coinbase Commerce	Only in the official Node SDK readme	9 exception classes	Exception classes mapped to HTTP statuses
OxaPay	Yes — Error reference	6 statuses, 0 code values	Response shape only; no example values
CoinGate	Yes — API error responses	5 reason strings	PascalCase reason beside an HTTP status
Cryptomus	No — documented per endpoint	12 message strings on the invoice page alone	Message strings, no code field
NOWPayments	No	3 code strings, inside example responses	SCREAMING_SNAKE_CASE, found only in examples
BTCPay Server	Schema only, in the Greenfield spec	0 enumerated values	{code, message} with code typed string and never enumerated

The spread in that third column is the story. BitPay publishes 26 codes, BTCPay Server publishes none, and they are both respected products with careful documentation elsewhere. BTCPay's Greenfield specification runs to 552 KB and defines the error object properly — {code, message}, with code described as an error code describing the error — and then never enumerates one value for it. We searched the whole spec for enumerated values on that field and found none.

NOWPayments is the opposite failure. Its API reference is a published Postman collection with 40 example responses, and the error vocabulary exists only inside five of them: NOT_FOUND, INVALID_REQUEST_PARAMS and BAD_REQUEST. There is no index, so the only way to learn the vocabulary is to read every endpoint — and the code you hit first is not among the three, as the next section shows.

One bad API key, nine different answers

A missing or wrong API key is the first error every integration meets, and the only one measurable across every gateway without an account. So we did: one request per gateway, no credentials, 4 October 2026, recording the wire status and the exact bytes.

Gateway	HTTP on the wire	Body we got back	Machine-readable code	Matches its own docs?
CoinGate	401	{"message":"Auth Token is not valid","reason":"BadAuthToken"}	reason: BadAuthToken	No — the published table maps 401 to BadCredentials; BadAuthToken is not in it
BlockBee	401	{"status":"error","error":"API Key not provided, please use api.cryptapi.io ..."}	None	Yes — verbatim, including the predecessor brand name
Cryptomus	401	{"message":"Invalid Sign."}	None	No — the docs show a {"state":1,...} envelope returned at HTTP 422
BitPay	401	{"error":"This endpoint does not support the `public` facade"}	None	No — not one of the 26 six-digit codes appears in the response
BTCPay Server	401	{"code":"unauthenticated","message":"Authentication is required ..."}	code: unauthenticated	Shape yes, value no — unauthenticated is nowhere in the 552 KB spec
NOWPayments	403	{"status":false,"statusCode":403,"code":"INVALID_API_KEY","message":"Invalid api key"}	code: INVALID_API_KEY	No — INVALID_API_KEY appears nowhere in its published collection
OxaPay	403	{"cf":{},"message":"The provided merchant API key is invalid...","error":{},"status":401}	None — error is an empty object	No — the wire says 403 and the body says 401
Plisio	422	{"status":"error","data":{...,"message":"Please check your secret key is correct ...","code":101,"status":422}}	data.code: 101	No — its own appendix maps authentication failure to 401 AUTHENTICATION_FAILURE
Coinbase Commerce	Not measurable	HTTP 503 and an HTML challenge page to a non-browser client	—	Its SDK documents AuthenticationError at 401

Five 401s, two 403s, one 422. Only 401 is the correct status for a missing credential, and a third of the gateways do not use it. That matters, because almost every HTTP client and retry wrapper in common use classifies by status family before it reads a body — and the two 403s will be read as a permissions problem on an otherwise authenticated request, which is the wrong diagnosis.

Plisio's 422 is the most interesting of the three. Its message is genuinely helpful — Please check your secret key is correct and domain is verified tells you about domain verification, a failure mode no other gateway in this set mentions — and it arrives with a numeric code: 101 nested two levels deep at data.code. It is the most actionable auth error we measured and the hardest to parse.

The HTTP status is not the error

OxaPay is the reason this section exists. Its response to a bad merchant key arrives with 403 on the wire and "status": 401 in the body. Both numbers are in the same response, and they disagree. We reproduced it twice, once with no key header and once with a deliberately wrong one, and got byte-identical bodies both times.

Then we sent OxaPay a mistyped path, and it answered 403 again — this time with "result": 404 in the body. So the wire status is 403 for a credential problem and 403 for a routing problem, the real status lives in the body, and the field holding it is named status on one error and result on the other. You cannot classify an OxaPay failure from its HTTP status, and you cannot classify it from a single body field either.

The practical rule that falls out of all nine measurements: read the body first and the status second, which is the reverse of how most HTTP clients are written. Where the two conflict, the body is the one the gateway's own application layer produced, so it is the one that reflects what the gateway thinks happened.

Three gateways change envelope shape mid-API

An error handler is written once and then trusted. That only works if the shape of an error is stable across a gateway's endpoints, so we tested the cheapest second error available: a path that does not exist.

Gateway	HTTP	content-type	Bytes	Body
NOWPayments	404	application/json	64	{"status":false,"statusCode":404,"message":"Endpoint not found"}
BlockBee	404	application/json	50	{"status":"error","error":"Resource not found"}
Cryptomus	404	application/json	21	{"error":"Not found"}
Plisio	404	application/json	66	{"status":"error","data":"Internal error. Please try again later"}
OxaPay	403	application/json	48	{"cf":{},"result":404,"message":"Not Found!"}
BTCPay Server	404	none sent	0	empty
CoinGate	301	text/html	0	Redirect to developer.coingate.com
BitPay	404	text/html	6,731	A single-page-app shell with a Loading... div
Coinbase Commerce	503	text/html	1,100	Bot challenge page

Cryptomus returns three different envelopes. Its documentation shows {"state":1,"errors":{...}}, an unauthenticated call returns a bare {"message":"Invalid Sign."} with no state field at all, and an unknown path returns a bare {"error":"Not found"}. Three shapes, one API, and a handler written against any one of them fails on the other two. A probe with a bogus merchant header gave a fourth message, Invalid Merchant Uuid., in the second shape.

BitPay and BTCPay Server fail in opposite directions, and both will crash a naive client. BitPay serves a 6,731-byte HTML single-page-app shell at text/html, so JSON.parse throws on a payment error. BTCPay sends zero bytes with no content type, so JSON.parse throws on an empty string. CoinGate avoids both by answering a bad API path with a 301 redirect to its documentation site — which means a mistyped CoinGate URL, in a library that follows redirects, hands you an HTML docs page with a 200.

NOWPayments is the only gateway in the set whose envelope held steady: {status, statusCode, code?, message} on both probes, with statusCode agreeing with the wire both times. For all the complaints above about where it hides its vocabulary, it is the one you can write one handler for.

Seven of eight contradict their own documentation

This is the finding we did not expect and the one that should change how you integrate. Of the eight gateways we could measure, exactly one returned what its documentation says it returns.

BlockBee is that one, and it is exact. Its error-handling guide lists API Key not provided, please use api.cryptapi.io if you don't have an API key under HTTP 401, and that is the string we got back, character for character — including the reference to cryptapi.io, the brand BlockBee operated under before it renamed. A documented string that still names a predecessor product is a sign somebody keeps the page in sync with the code.

The other seven drift in three distinguishable ways, and the distinction matters because the fixes differ:

• Undocumented values. CoinGate's published table maps 401 to BadCredentials; the live API returns BadAuthToken. NOWPayments returns INVALID_API_KEY, which is in neither its collection nor any page we could find. BTCPay returns unauthenticated, a value its specification permits and never names. In each case an engineer writing a switch from the docs produces a handler with no matching branch.
• Wrong status in the docs. Cryptomus documents its errors at HTTP 422 and returns 401. Plisio documents authentication failure as 401 AUTHENTICATION_FAILURE and returns 422 with a numeric code. Neither shows up in testing, because a test with a valid key never exercises it.
• A documented scheme the API does not use. BitPay publishes 26 six-digit codes and then answers an unauthorised call with {"error":"This endpoint does not support the `public` facade"} — no code field at all. The scheme is real and covers invoices and refunds; it is not what you get at the authentication layer.

BitPay's 6-digit scheme is the good idea nobody copied

Worth separating out, because it is the only design in this set that solves the actual problem. BitPay's codes are six digits where the digits carry meaning.

Digits	What they encode	Values BitPay publishes
1–2	HTTP method	00 generic, 01 POST, 02 GET, 03 PUT, 04 DELETE
3–4	Resource	00 unmapped, 01 invoice, 02 refund
5–6	The specific fault	26 suffixes, e.g. 0110 price below minimum, 0111 price above maximum, 0117 invalid invoice state, 0207 invalid invoice state for refund

So 010110 is a POST to invoices that failed because the price is below the minimum, and you know all three of those facts before you read the message. The method lives in the code, so a log line locates the call without the request beside it. Across 5 method prefixes, the 26 suffixes give the scheme room for 130 concrete codes.

Nobody else does this. The nearest comparison in the whole search result set is not a merchant gateway at all: Circle's payment network publishes 58-plus numeric codes in 6 tables, with blockchain-specific values a merchant gateway would be useful to have — 290313 INSUFFICIENT_GAS_BALANCE, 290315 GAS_PRICE_TOO_LOW, 290202 QUOTE_EXPIRED. It is the most complete error reference in this niche, and it belongs to a network none of the nine runs on.

Mapping nine gateway error-code vocabularies to five buckets

You do not need to model nine error schemes. You need five decisions — fixable by me, by the caller, by waiting, or by nobody — and a ten-line mapping layer per gateway. Here is the mapping we would write from the measurements above.

Your bucket	Retry?	Signals that mean it, across the nine	The one that will catch you out
Bad credentials	Never	HTTP 401 (CoinGate, BlockBee, Cryptomus, BitPay, BTCPay), HTTP 403 (NOWPayments, OxaPay), HTTP 422 with code 101 (Plisio)	NOWPayments and OxaPay answer 403, which most HTTP clients classify as a permissions problem rather than a key problem
Not found	Never	HTTP 404 with JSON (NOWPayments, BlockBee, Cryptomus, Plisio), HTTP 404 with no body (BTCPay)	OxaPay answers 403 with result: 404, so the status is wrong and the field name is not status
Validation	Never, until the caller changes	HTTP 400 with a message string (BlockBee, NOWPayments), HTTP 422 array of {path, message} (BTCPay)	BTCPay's validation body is a JSON array, not an object — a handler that reads body.message gets undefined
Rate limited	Yes, with backoff	HTTP 429 RateLimitException (CoinGate), 429 RATE_LIMIT_REACHED (Plisio), RateLimitExceededError (Coinbase Commerce)	OxaPay documents no 429 at all and returns x-ratelimit-limit headers instead, so the only warning is a header nobody reads
Transient	Yes, with backoff	HTTP 500/503 (every gateway), BlockBee's please try again later	Plisio returns Internal error. Please try again later for a misspelled URL, which no amount of retrying will fix

The fourth column is the one to read twice: every row has a gateway that breaks the obvious rule, and in four of five it is one that looks correct until you test it. Put the mapping in a small adapter per gateway, not in your business logic — when a vendor changes a string you want one file to edit.

Where a gateway gives you no code at all — BlockBee, Cryptomus, BitPay and OxaPay — match on a substring, not the whole message, and log the full body whenever no branch matches. Message text gets reworded without notice, and an unmatched error that reaches your logs intact is recoverable; one swallowed into a generic failure is not.

What this means for your retry logic

Retry rules written against HTTP status families are wrong on these APIs, and wrong expensively: they retry what cannot succeed and give up on what could.

Do not retry 403 on a crypto gateway. On NOWPayments it means the key is wrong; on OxaPay it means the key is wrong or the path is. Neither improves with backoff, and a retry loop against an auth failure spends your rate-limit budget on a request that can never work — CoinGate allows 200 requests a minute and only two of nine gateways publish a figure at all, so that budget is mostly invisible to you.

Do not treat 422 as permanent. It usually is, which is what makes Plisio's auth 422 dangerous: the fix is to correct the key or verify the domain, which an operator can do, so the right behaviour is to alert rather than to drop the payment. Do not read an empty body as a network failure either — BTCPay returns zero bytes on a 404, and a client that treats that as a dropped connection retries a URL that will never exist.

FAQ

Affiliate disclosure: payyd.co earns a commission on sign-ups made through our /go/ links, including the NOWPayments link above. No gateway supplied, reviewed or saw these findings before publication. Method: on 4 October 2026 we read the first-party error references these nine publish — BitPay's error-codes page, CoinGate's common errors, BlockBee's error-handling guide, OxaPay's error reference, the BTCPay Greenfield specification, Cryptomus's invoice endpoint, Plisio's HTTP status-code appendix, NOWPayments' published Postman collection and the official Coinbase Commerce Node SDK — then sent each live API an unauthenticated request and a mistyped path, recording the wire status, content type, byte count and exact body. Circle's CPN error codes are quoted for comparison only; Circle is not one of the nine. Figures are as at 4 October 2026; error vocabularies change without notice.