Error catalog

Every error the TensorRail API returns nests under a top-level error key and carries a stable ERR_NNNN code. code is the field to branch on: it is the only one present everywhere.

There are two envelopes, and which you get depends on the endpoint:

Endpoints	Body
/payments, /refunds, /customers, /disputes	{ "error": { "type", "message", "code" } }, plus context fields such as field_name where they apply
/v1/* (reporting, account, API keys)	{ "error": { "code", "slug", "message", "retriable", "user_action", "doc_url", "request_id" } }

So slug, retriable, user_action and doc_url are available on the /v1/* surface and should not be relied on when handling a failed payment or refund. Branch on code and you are correct on both. This page documents the code values you meet on the common integration paths, grouped by family. For the family semantics, the wire shape, and a handling recipe, see Error intelligence.

Treat it as a reference rather than a closed set: it grows as the platform does. Because every error body carries its own code, a code you have not met before is still handleable from the response alone: read the band for the family semantics, and look the code up here for whether re-attempting can succeed.

A small number of catalogued codes are not returned by any current code path; they stay on the page, under Reserved codes, rather than being deleted, so a code quoted in an older integration or a support ticket is still explained.

Branch on code, never on message

Codes are stable contract; message strings are for humans and logs and can change. When a code is retriable, always retry with the same Idempotency-Key.

Settlement codes are catalogue entries, not a merchant surface

ERR_3006, ERR_3040 to ERR_3043 and ERR_3045 to ERR_3048 belong to settlement, which is not self-served on the merchant API: /v1/settlements* and /v1/payouts return 404. Anything past reading your balance is arranged with your account manager. These codes are listed for completeness of the catalogue; you will not meet them on the endpoints this documentation covers. See Balances.

Family	Band	Codes documented here
Authentication and authorization	ERR_1xxx	20
Request validation	ERR_2xxx	14
Business state	ERR_3xxx	41
Payment and decline	ERR_4xxx	63
Server and rate limits	ERR_5xxx	14
Account policy and compliance	ERR_6xxx	7
Total		159

Authentication and authorization (ERR_1xxx)

Credential and session problems. Fix your configuration; never retry these blindly.

Code	HTTP	Retriable	What it means	What to do
ERR_1001	401	no	An API key is required.	Include your API key in the Authorization: Bearer <key> header.
ERR_1002	401	no	The API key is invalid.	Check that the key was copied correctly. If you suspect the key is compromised, use Emergency revoke in your dashboard: it stops the key immediately.
ERR_1003	401	no	The API key has expired.	Use the replacement key issued when this key was rotated, or create a new key in your dashboard.
ERR_1004	403	no	The API key lacks the required scope for this operation.	Use a key with the necessary scopes, or update the existing key's scopes.
ERR_1005	403	no	The merchant account is not active.	Contact support to reactivate the account.
ERR_1006	403	no	The request origin IP is not on the allowed list.	Add that address to your IP allowlist from a machine that is already allowlisted. If no allowlisted machine is reachable, contact support: the allowlist is enforced fail-closed and cannot be edited from a blocked address.
ERR_1007	401	no	Your session has expired.	Sign in again.
ERR_1008	401	no	The session is invalid.	Sign in again.
ERR_1009	401	no	This operation requires a confirmation token.	Initiate the confirmation flow before retrying.
ERR_1010	401	no	The confirmation token is invalid.	Request a fresh confirmation token.
ERR_1011	401	no	Unauthorized.	Verify your credentials and try again.
ERR_1012	403	no	Forbidden.	This operation is not permitted with the current credentials.
ERR_1013	401	no	Sign-in credentials are invalid.	Verify email and password and try again.
ERR_1014	401	yes	The verification code is invalid.	Generate a fresh code from your authenticator app.
ERR_1015	401	no	Credentials are invalid.	Verify the credentials and retry.
ERR_1018	401	no	Unauthorized for this operation.	Verify credentials and required scope.
ERR_1019	401	yes	This action requires two-factor verification.	Provide a fresh 6-digit code from your authenticator app and retry.
ERR_1020	401	yes	The two-factor verification window has expired.	Re-verify with a fresh authenticator code and retry.
ERR_1021	401	yes	The two-factor verification proof is invalid.	Re-verify with a fresh authenticator code and retry.
ERR_1022	401	no	This action requires two-factor authentication, which is not set up on your account.	Set up two-factor authentication in Settings, then retry this action.

Request validation (ERR_2xxx)

Your call was malformed. Fix the request; the field context in the error body tells you where.

Code	HTTP	Retriable	What it means	What to do
ERR_2001	400	no	A required field is missing from the request.	Add the missing field per the API reference.
ERR_2002	400	no	A field has an invalid format.	Reformat the value per the API reference.
ERR_2003	400	no	A field value is out of the allowed range.	Adjust the value to fall within the documented range.
ERR_2004	400	no	The currency is not supported.	Use a supported currency.
ERR_2007	415	no	The request body is not valid JSON.	Verify the body is valid JSON.
ERR_2008	413	no	The request body exceeds the maximum size.	Reduce the payload size.
ERR_2009	400	no	The API version is not supported.	Use a supported API version per the API reference.
ERR_2010	400	no	The parameter combination is not supported.	Adjust the parameters per the API reference.
ERR_2011	400	no	A threshold value is invalid.	Verify the threshold falls in the documented range.
ERR_2012	405	no	The HTTP method is not allowed on this endpoint.	Use the correct method per the API reference.
ERR_2013	422	no	The password does not meet policy requirements.	Use a password meeting the documented requirements.
ERR_2014	400	no	The query parameter combination is not supported.	Adjust the parameters per the API reference.
ERR_2029	422	no	The request cannot be processed as submitted.	Review the request against the API reference.
ERR_2030	501	no	This operation is not yet implemented.	This endpoint or operation is not available. Check the API reference for supported operations.

Business state (ERR_3xxx)

The request was valid but the resource's current state does not allow it. Retrieve the resource and branch on its actual state rather than looping.

Code	HTTP	Retriable	What it means	What to do
ERR_3001	422	no	The available balance is insufficient for this operation.	Top up the merchant balance or reduce the requested amount.
ERR_3002	409	no	The Idempotency-Key was reused with a different request body.	Use a fresh Idempotency-Key or retry with the original body.
ERR_3003	404	no	The payment was not found.	Verify the payment ID.
ERR_3004	422	no	The resource cannot transition from its current state to the requested state.	Check the resource's current state.
ERR_3005	422	no	The refund amount exceeds the captured amount.	Reduce the refund amount to at most the captured amount.
ERR_3007	409	no	The API key has already been rotated.	Use the replacement key issued by that rotation. Your dashboard lists every key with its status.
ERR_3008	409	yes	The API key rotation cooldown is still active.	Wait for the cooldown to elapse before rotating again, or use emergency revoke.
ERR_3009	409	no	The resource has already been provisioned.	Use the existing resource or remove it before re-provisioning.
ERR_3010	422	no	Provisioning must complete before this operation.	Initiate provisioning from the dashboard.
ERR_3011	404	no	The merchant was not found.	Verify the merchant identifier.
ERR_3012	404	no	The resource was not found.	Verify the resource identifier.
ERR_3014	422	no	Retry is not supported for this payment method.	This payment cannot be retried in its current state.
ERR_3015	422	no	The confirmation token has expired.	Request a fresh confirmation token.
ERR_3016	404	no	The customer was not found.	Verify the customer identifier.
ERR_3017	404	no	The refund was not found.	Verify the refund identifier.
ERR_3018	409	no	The resource already exists in our records.	Use the existing resource or modify the request to avoid the conflict.
ERR_3019	409	no	The customer has an active mandate.	Cancel the existing mandate before creating a new one.
ERR_3020	422	no	Mandate validation failed.	Review the mandate parameters.
ERR_3022	409	no	The API key has already been revoked.	This is a no-op; the key was already inactive.
ERR_3023	422	no	Emergency key revocation requires a confirmation token in the request body.	Include the typed confirmation value in the request body.
ERR_3024	422	no	The payment ID is invalid for this operation.	Verify the payment ID and operation context.
ERR_3025	422	no	The maximum refund attempt count has been reached.	No further refunds can be issued on this payment.
ERR_3027	409	yes, after 5s	A ledger transaction is still being posted.	Retry after a short delay; contact support if the condition persists.
ERR_3028	404	no	The referenced ledger transaction was not found.	Verify the parent payment or ledger identifiers.
ERR_3029	409	no	This ledger operation was already completed.	Treat the request as a duplicate; no further action is required.
ERR_3033	404	no	The payment to refund was not found.	Verify the payment ID belongs to this account.
ERR_3034	422	no	This payment cannot be refunded in its current state.	Only successfully captured payments can be refunded.
ERR_3035	422	no	The refund amount exceeds the remaining refundable balance on this payment.	Reduce the refund amount to the remaining balance.
ERR_3039	422	no	The payment processor rejected this refund request.	Review the payment state and try again, or contact support with the refund identifier.
ERR_3040	404	no	The settlement cycle was not found.	Verify the cycle identifier or contact support.
ERR_3041	404	no	The settlement request was not found.	Verify the request identifier.
ERR_3042	409	no	This operation is not valid for the settlement request in its current state.	Refresh the request status and try again, or contact support.
ERR_3043	410	no	The agent quote has expired.	Request a fresh quote from support.
ERR_3045	404	no	The saved wallet address was not found.	Select a valid saved wallet or add a new one.
ERR_3046	422	no	The wallet chain does not match the request.	Use a wallet that matches the selected chain.
ERR_3047	403	no	Self-service settlement requests are not enabled for this account yet.	Contact support to initiate settlement during onboarding.
ERR_3048	424	no	A remittance agent is not assigned to this corridor configuration.	Contact support to complete corridor configuration.
ERR_3051	422	no	The API key's mode (test or live) does not match this operation.	Use the correct test or live API key for this environment.
ERR_3066	422	no	This payment's method has no refund API.	Ask your account manager for the refund: it is returned to the payer as a payout, and you bear the payout fee.
ERR_3069	422	no	No refund fee is configured in this payment's currency, so the refund cannot be priced.	Contact your account manager to have the refund fee set for this currency. Nothing was refunded and nothing was charged.
ERR_3070	409	no	This rail cannot be enabled until every listed prerequisite is met.	Resolve each prerequisite in the blockers list, then try again. Nothing was changed.

Payment and decline (ERR_4xxx)

The payment was attempted and did not succeed. Whether to retry depends on retriable.

Code	HTTP	Retriable	What it means	What to do
ERR_4001	402	no	The card has expired.	Ask the customer for a current card.
ERR_4002	402	no	The card was reported lost.	Decline retry on this card. Request a different payment method.
ERR_4003	402	no	The card was reported stolen.	Decline retry on this card. Flag for fraud review on repeat customers.
ERR_4004	402	no	The card is restricted for this type of transaction.	Customer should contact card issuer or try a different card.
ERR_4005	400	no	The card number is invalid.	Have the customer re-enter the card number.
ERR_4006	400	yes	The security code (CVC) is invalid.	Have the customer re-enter the CVC.
ERR_4007	400	no	The card expiry date is invalid.	Have the customer re-enter the expiry.
ERR_4008	402	no	The card issuer declined the transaction without a specific reason.	Customer should contact their card issuer or use a different payment method.
ERR_4009	402	no	The card issuer requested the card be retained.	Do not retry. Treat as a security event; advise customer to contact issuer.
ERR_4010	402	no	The card is blocked.	Customer should contact their card issuer.
ERR_4011	402	yes	The PIN is incorrect.	Have the customer re-enter the PIN.
ERR_4012	402	yes, after 3600s	The card has exceeded its allowed transaction frequency.	Retry in an hour or use a different card.
ERR_4013	402	no	The card account is closed.	Request a different payment method.
ERR_4014	402	no	The card account is invalid.	Customer should verify card details with their issuer.
ERR_4015	402	no	This card network is not supported.	Customer should use a different card brand or payment method.
ERR_4016	402	no	The card issuer requires manual authorization.	Customer should contact their card issuer to authorize, then retry.
ERR_4017	402	no	The CVC check failed.	Have the customer verify the CVC; decline retry if it still fails.
ERR_4018	402	no	The address verification check failed.	Have the customer verify the billing address with their issuer.
ERR_4019	402	yes	The ZIP/postal code did not match.	Have the customer verify the ZIP/postal code.
ERR_4020	402	yes	The card has insufficient funds.	Customer should retry with a card that has sufficient balance.
ERR_4021	402	yes, after 86400s	The card has reached its allowed transaction count for the period.	Retry tomorrow or use a different card.
ERR_4022	402	no	The transaction amount exceeds the card's per-transaction limit.	Split into smaller transactions or use a different card.
ERR_4024	402	yes, after 86400s	The card has reached its allowed limit in this currency.	Retry later or use a different currency.
ERR_4025	402	yes, after 86400s	The card has reached its daily spending limit.	Retry after 24 hours or use a different card.
ERR_4026	402	yes, after 2592000s	The card has reached its monthly spending limit.	Retry next month or use a different card.
ERR_4027	402	yes, after 3600s	The transaction was declined due to high-frequency activity.	Wait an hour and retry, or use a different payment method.
ERR_4028	402	no	The cumulative transaction volume limit has been reached.	Contact support to raise limits.
ERR_4030	503	yes, after 30s	The card issuer is temporarily unavailable.	Retry in 30 seconds.
ERR_4031	504	yes, after 15s	The card issuer did not respond in time.	Retry in 15 seconds.
ERR_4032	503	yes, after 60s	No route is available to the card network.	Retry in 1 minute.
ERR_4040	402	no	This transaction was blocked due to a high-confidence fraud signal.	Do not retry. Investigate the customer or order.
ERR_4041	402	yes	This transaction was flagged for review.	Step up to 3DS authentication or contact the customer to verify before retrying.
ERR_4042	402	no	The card matched a fraud blocklist.	Do not retry. Treat as a confirmed fraud signal.
ERR_4043	402	yes, after 3600s	High-frequency activity from this customer matched a fraud rule.	Wait an hour or step up authentication.
ERR_4044	402	yes	The transaction location does not match the card's country of issue.	If legitimate, ask the customer to authenticate via 3DS, then retry.
ERR_4045	402	yes	The device used has a high fraud risk score.	Step up to 3DS or contact the customer to verify identity.
ERR_4046	402	yes	The IP address has a high fraud risk score.	Step up to 3DS or contact the customer to verify.
ERR_4047	402	no	The transaction was blocked by your merchant fraud filter.	Review your fraud-filter configuration if this was a false positive.
ERR_4048	402	yes	Cardholder authentication failed during fraud verification.	Retry with a fresh authentication challenge.
ERR_4060	402	yes	Strong customer authentication is required for this transaction.	Initiate a 3DS challenge and retry.
ERR_4061	402	yes	The cardholder failed 3DS authentication.	Ask the customer to try again or use a different card.
ERR_4063	402	yes	The cardholder did not complete 3DS authentication in time.	Retry the 3DS challenge.
ERR_4064	503	yes, after 30s	A technical issue occurred during 3DS authentication.	Retry in 30 seconds.
ERR_4065	503	yes, after 30s	The card issuer's authentication service is unavailable.	Retry in 30 seconds.
ERR_4066	402	no	The card issuer declined to authenticate the cardholder.	Customer should contact their issuer.
ERR_4067	402	yes	This transaction requires Strong Customer Authentication (SCA) under PSD2.	Initiate an SCA challenge (typically 3DS2).
ERR_4068	402	yes	Frictionless 3DS is not available; a challenge is required.	Initiate a challenge-flow 3DS authentication.
ERR_4080	503	yes, after 60s	A temporary error occurred.	Retry after a brief delay.
ERR_4081	502	yes, after 30s	An error occurred while processing the payment.	Retry in 30 seconds.
ERR_4082	504	yes, after 15s	The payment processor did not respond in time.	Retry in 15 seconds.
ERR_4083	503	yes, after 60s	The payment processor could not be reached.	Retry in 1 minute.
ERR_4084	503	yes, after 120s	The payment service is temporarily unavailable.	Retry in 2 minutes.
ERR_4085	400	no	The currency is not supported by this payment route.	Use a different currency or payment method.
ERR_4086	400	no	The cardholder country is not supported for this transaction.	Customer should use a different payment method.
ERR_4087	400	no	This payment method is not supported by the selected processor.	Try a different payment method or contact support.
ERR_4088	503	no	The payment route is misconfigured.	Contact support. This is a merchant-side configuration issue.
ERR_4089	503	no	The payment route is currently disabled.	Contact support to enable the route, or use a different route.
ERR_4090	503	yes, after 60s	No suitable payment route is available.	Retry in 1 minute; if persistent, contact support.
ERR_4091	503	yes, after 60s	The acquirer network could not be reached.	Retry in 1 minute.
ERR_4093	400	no	The payment processor rejected the request format.	Contact support. This typically indicates an integration issue.
ERR_4094	402	no	The payment was declined.	Customer should contact their card issuer or use a different payment method.
ERR_4098	503	yes, after 300s	The payment rail is temporarily unavailable.	Retry in 5 minutes, or route through a different payment method while the rail is down.
ERR_4099	402	no	The payment was declined for an unspecified reason.	Contact support if this persists; the failure will be reviewed and reclassified.

Server and rate limits (ERR_5xxx)

Our side, or you are going too fast. These are the ones worth retrying with backoff.

Code	HTTP	Retriable	What it means	What to do
ERR_5003	504	yes, after 15s	An upstream service timed out.	Retry in 15 seconds.
ERR_5004	500	yes, after 30s	A database operation failed.	Retry in 30 seconds; contact support if persistent.
ERR_5005	503	yes, after 60s	An upstream service is unavailable.	Retry in 1 minute.
ERR_5006	503	no	The payment service is not configured for this operation.	Contact support. This is a configuration issue.
ERR_5007	503	yes, after 5s	The idempotency check timed out.	Retry in 5 seconds.
ERR_5008	500	yes, after 30s	Failed to persist the payment intent.	Retry in 30 seconds.
ERR_5009	500	yes, after 30s	Audit logging failed.	Retry; contact support if persistent.
ERR_5010	503	yes, after 30s	A sync operation failed.	Retry in 30 seconds.
ERR_5097	500	yes, after 30s	A data integrity check failed.	Retry; contact support if persistent.
ERR_5098	500	no	A configuration error occurred.	Contact support. This is a configuration issue.
ERR_5099	500	yes, after 30s	An internal error occurred.	Retry; contact support if persistent.
ERR_5101	429	yes	Request rate exceeded.	Retry after the period indicated by the Retry-After header.
ERR_5103	429	yes	This sensitive operation has been rate-limited.	Wait before retrying; sensitive operations have lower rate limits than general traffic.
ERR_5999	500	no	An unknown error occurred.	Contact support; this error has been logged for review.

Account policy and compliance (ERR_6xxx)

Account-level rules. These need a person, usually your account manager.

Code	HTTP	Retriable	What it means	What to do
ERR_6005	413	no	The uploaded file exceeds the size limit.	Reduce the file size and re-upload.
ERR_6006	415	no	The file type is not permitted.	Re-upload using a supported file type.
ERR_6101	404	no	The compliance certificate was not found.	Verify the certificate identifier.
ERR_6102	400	no	The compliance certificate type is invalid.	Use a supported certificate type.
ERR_6103	422	no	The compliance certificate cannot transition from its current state to the requested state.	Check the certificate's current state.
ERR_6104	422	no	The compliance certificate is expired or has invalid dates.	Renew or correct the certificate dates.
ERR_6106	400	no	Compliance certificate validation failed.	Review the certificate fields.

Reserved codes (not currently returned)

Cataloged but returned by no current code path (reserved for a future control, or retired). If you handle a code below in your integration, it is defensive, not load-bearing: nothing live sends it today.

Code	Status	What it would mean
ERR_2005	Reserved	The amount is below the minimum allowed.
ERR_2006	Reserved	The amount exceeds the maximum allowed.
ERR_3006	Reserved	The settlement amount is below the minimum threshold.
ERR_3021	Reserved	The payment has not succeeded.
ERR_3026	Reserved	The payment route is disabled.
ERR_3050	Retired	No longer assigned. Refunds were once closed with this code after repeated delivery attempts; a refund whose outcome is not yet confirmed now stays in progress with its amount reserved.
ERR_4023	Reserved	The transaction amount is below the minimum.
ERR_4029	Reserved	The transaction exceeds the merchant floor limit.
ERR_4062	Reserved	This card does not support 3DS authentication.
ERR_4092	Reserved	The acquirer declined the transaction.
ERR_4095	Reserved	The customer paid less than the requested amount.
ERR_4096	Reserved	The customer paid more than the requested amount.
ERR_4097	Reserved	The payment was not confirmed within the expected window.
ERR_5102	Reserved	Merchant quota exceeded.
ERR_6001	Reserved	KYB verification is required before this operation.
ERR_6002	Reserved	KYB verification is pending.
ERR_6003	Reserved	The entity is on the blocklist.
ERR_6004	Reserved	A velocity limit was exceeded.
ERR_6105	Reserved	A duplicate compliance record exists.