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.

Family	Band	Codes documented here
Authentication and authorization	ERR_1xxx	19
Request validation	ERR_2xxx	16
Business state	ERR_3xxx	45
Payment and decline	ERR_4xxx	70
Server and rate limits	ERR_5xxx	16
Account policy and compliance	ERR_6xxx	12

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.

Authentication and authorization (ERR_1xxx)

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

Code	Meaning	Typical cause / what to do
ERR_1001	Missing API key	No Authorization: Bearer <key> header on the request. Include your API key.
ERR_1002	Invalid API key	The key was mistyped, truncated, or revoked. Check the key; rotate it if you suspect compromise.
ERR_1003	Expired API key	The key passed its expiry. Rotate the key from your dashboard.
ERR_1004	Insufficient scope	The key lacks the scope this operation needs. Use a key with the necessary scopes or update the key's scopes.
ERR_1005	Merchant account inactive	Your account is not active. Contact support to reactivate it.
ERR_1006	IP not allowed	The request came from an IP that is not on your allowlist. Add the originating IP in the dashboard.
ERR_1007	Session expired	Your dashboard session timed out. Sign in again.
ERR_1008	Session invalid	The dashboard session could not be validated. Sign in again.
ERR_1009	Confirmation required	This operation needs a confirmation token. Initiate the confirmation flow before retrying.
ERR_1010	Invalid confirmation	The confirmation token did not validate. Request a fresh confirmation token.
ERR_1011	Unauthorized	The Authorization header is present but not usable (wrong scheme or empty token). Verify your credentials.
ERR_1012	Forbidden	The operation is not permitted with the current credentials. Use credentials with the required permissions.
ERR_1013	Invalid credentials	Sign-in email or password is wrong. Verify and try again.
ERR_1014	Invalid verification code	The two-factor code did not validate. Generate a fresh code from your authenticator app.
ERR_1015	Invalid basic authentication	Basic auth credentials on this endpoint are wrong. Verify the credentials and retry.
ERR_1018	Unauthorized for this operation	A generic authorization failure. Verify credentials and the required scope.
ERR_1019	Two-factor verification required	You invoked a sensitive action without recent two-factor verification. Provide a fresh 6-digit authenticator code and retry.
ERR_1020	Two-factor window expired	Your step-up verification aged out. Re-verify with a fresh authenticator code and retry.
ERR_1021	Two-factor proof invalid	The step-up verification proof did not validate. Re-verify with a fresh authenticator code and retry.

Request validation (ERR_2xxx)

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

Code	Meaning	Typical cause / what to do
ERR_2001	Missing required field	A required field is absent. The error indicates which field; add it.
ERR_2002	Invalid format	A field value has the wrong format. Reformat per the API reference; the error includes the expected format.
ERR_2003	Value out of range	A field value falls outside the allowed range. Adjust it to the documented range.
ERR_2004	Unsupported currency	The currency is not supported for this request. Use a supported currency from the API reference.
ERR_2005	Amount too small	The amount is below the minimum. Increase it to meet the minimum.
ERR_2006	Amount too large	The amount exceeds the maximum. Reduce it or split the transaction.
ERR_2007	Invalid JSON	The request body is not valid JSON. Verify your serialization.
ERR_2008	Payload too large	The request body exceeds the size limit. Reduce the payload.
ERR_2009	Unsupported API version	The Tensorrail-Version header names a version that is not supported. Use a supported version.
ERR_2010	Unsupported combination	The parameter combination is not supported together. Adjust per the API reference.
ERR_2011	Invalid threshold	A threshold value is invalid. Keep it within the documented range.
ERR_2012	Method not allowed	The HTTP method is wrong for this endpoint. Use the method the API reference documents.
ERR_2013	Password policy violation	The password does not meet policy. Choose one meeting the documented requirements.
ERR_2014	Unsupported query combination	The query parameters cannot be combined this way. Adjust per the API reference.
ERR_2029	Unprocessable request	The request is well formed but cannot be processed as submitted. Review it against the API reference.
ERR_2030	Not implemented	The 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. Usually a logic bug or a race on your side; retrieve the resource and branch on its actual state rather than looping.

Code	Meaning	Typical cause / what to do
ERR_3001	Insufficient balance	The available balance does not cover the operation. Top up or reduce the requested amount.
ERR_3002	Duplicate idempotency key	You reused an Idempotency-Key with a different request body on POST /v1/refunds. Almost always a key-generation bug; use a fresh key or retry with the original body. Only the /v1/* surface compares bodies — POST /payments and POST /refunds replay the original resource instead of raising this.
ERR_3003	Payment not found	The payment ID does not exist on this account. Verify the ID.
ERR_3004	Invalid state transition	The resource cannot move from its current state to the requested one, for example capturing a payment that is not awaiting capture. Retrieve the resource and branch on its status.
ERR_3005	Refund exceeds capture	The refund amount is larger than the captured amount. Reduce it to at most the captured amount.
ERR_3006	Settlement below minimum	The settlement amount is under your threshold. Wait for the balance to reach the threshold or update it in settings.
ERR_3007	Key already rotated	The API key was already rotated. Use the latest key, or check rotation history in the dashboard.
ERR_3008	Rotation cooldown active	You rotated recently and the cooldown has not elapsed. Wait, or use emergency revoke. The response includes retry_after_seconds.
ERR_3009	Already provisioned	The resource already exists from a prior provisioning. Use the existing resource.
ERR_3010	Provisioning required	Account provisioning has not completed. Finish setup from the dashboard before this operation.
ERR_3011	Merchant not found	The merchant identifier does not resolve. Verify it.
ERR_3012	Resource not found	The referenced resource does not exist. Verify the identifier; the error message says which resource.
ERR_3013	Invalid fee schedule	The fee configuration for this operation is invalid. Contact support if you cannot resolve it from settings.
ERR_3014	Retry not supported	This payment method cannot be retried in its current state. Create a new payment instead.
ERR_3015	Confirmation expired	The confirmation token aged out. Request a fresh one.
ERR_3016	Customer not found	The customer identifier does not resolve. Verify it.
ERR_3017	Refund not found	The refund identifier does not resolve. Verify it.
ERR_3018	Duplicate resource	The resource already exists. Use the existing one; the error message says which resource collided.
ERR_3019	Mandate already active	The customer has an active mandate. Cancel it before creating a new one.
ERR_3020	Mandate validation failed	The mandate parameters did not validate. Review them against the API reference.
ERR_3021	Payment not succeeded	The operation requires a succeeded payment. Wait for the payment to complete first.
ERR_3022	Key already revoked	The key was already inactive. Treat as a no-op.
ERR_3023	Emergency revoke needs confirmation	Emergency key revocation requires the typed confirmation value in the request body. Include it.
ERR_3024	Invalid payment ID	The payment ID is not valid for this operation. Verify the ID and the operation context.
ERR_3025	Maximum refund count reached	No further refunds can be issued on this payment.
ERR_3026	Payment route disabled	The route this request needs is disabled. Enable it from the dashboard or use a different route.
ERR_3027	Ledger posting in progress	A ledger transaction is still being posted. Retry after a short delay; contact support if it persists.
ERR_3028	Ledger transaction not found	The referenced ledger transaction does not exist. Verify the parent payment or ledger identifiers.
ERR_3029	Ledger operation already completed	The ledger operation was already applied. Treat as a duplicate; no action needed.
ERR_3032	Refund in flight	A refund with this idempotency key is already processing. Wait, then retry with the same key to fetch the result.
ERR_3033	Refund payment not found	The payment you are refunding was not found on this account. Verify the payment ID.
ERR_3034	Payment not refundable	Only successfully captured payments can be refunded. Check the payment's state.
ERR_3035	Refund exceeds remaining balance	The refund amount is larger than what is still refundable on this payment. Reduce it.
ERR_3039	Refund rejected	The refund was rejected during processing. Review the payment state and try again, or contact support with the refund identifier.
ERR_3040	Settlement cycle not found	The settlement cycle identifier does not resolve. Verify it or contact support.
ERR_3041	Settlement request not found	The settlement request identifier does not resolve. Verify it.
ERR_3042	Settlement request in wrong state	The operation is not valid for the request's current state. Refresh the status and try again, or contact support.
ERR_3043	Settlement quote expired	The quote aged out before acceptance. Request a fresh quote from support.
ERR_3044	Quote acceptance must be merchant-side	This acceptance step must be completed by your merchant account. Sign in with a merchant user to accept or reject the quote.
ERR_3045	Saved wallet not found	The saved wallet address does not exist. Select a valid saved wallet or add a new one.
ERR_3046	Wallet chain mismatch	The wallet's chain does not match the request. Use a wallet on the selected chain.
ERR_3047	Settlement requests not enabled	Self-service settlement is not enabled for your account yet. Contact support to initiate settlement during onboarding.
ERR_3048	Settlement corridor not configured	The corridor configuration for this settlement is incomplete. Contact support to complete it.
ERR_3050	Refund delivery failed	The refund could not be delivered to the payment processor after repeated attempts. Contact support with the refund identifier.
ERR_3051	Mode mismatch	A test key touched a live resource or vice versa. Check which key your environment loaded; test and live data never mix.

Settlement codes are catalogue entries, not a merchant surface

ERR_3040–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.

Payment and decline (ERR_4xxx)

Collection outcomes from the issuer, network, or acquirer layer. These usually appear as error_code on a payment with status: "failed", not as API request errors. Route them to your checkout's retry experience, not to your alerting.

Card declines and card data (4001 to 4019)

Code	Meaning	Typical cause / what to do
ERR_4001	Card expired	Ask the customer for a current card.
ERR_4002	Card reported lost	Decline retry on this card. Request a different payment method.
ERR_4003	Card reported stolen	Decline retry on this card. Flag repeat customers for fraud review.
ERR_4004	Card restricted	The card cannot be used for this transaction type. The customer should contact their issuer or try a different card.
ERR_4005	Invalid card number	Have the customer re-enter the card number.
ERR_4006	Invalid CVC	Have the customer re-enter the security code.
ERR_4007	Invalid expiry	Have the customer re-enter the expiry date.
ERR_4008	Do not honor	The issuer declined without a specific reason. The customer should contact their issuer or pay another way.
ERR_4009	Pickup card	The issuer asked for the card to be retained. Do not retry; treat as a security event.
ERR_4010	Card blocked	The customer should contact their card issuer.
ERR_4011	Incorrect PIN	Have the customer re-enter the PIN.
ERR_4012	Card velocity exceeded	The card hit its transaction-frequency limit. Retry in an hour or use a different card.
ERR_4013	Account closed	The card account is closed. Request a different payment method.
ERR_4014	Invalid account	The card account is invalid. The customer should verify details with their issuer.
ERR_4015	Card network not supported	The customer should use a different card brand or payment method.
ERR_4016	Issuer requires call	The issuer needs manual authorization. The customer should contact their issuer, then retry.
ERR_4017	CVC check failed	Have the customer verify the CVC; decline retry if it still fails.
ERR_4018	Address check failed	Have the customer verify the billing address with their issuer.
ERR_4019	Postal code check failed	Have the customer verify the ZIP or postal code.

Funds and limits (4020 to 4032)

Code	Meaning	Typical cause / what to do
ERR_4020	Insufficient funds	The customer should retry with a card that has sufficient balance.
ERR_4021	Transaction count limit reached	The card hit its allowed count for the period. Retry tomorrow or use a different card.
ERR_4022	Amount over per-transaction limit	Split into smaller transactions or use a different card.
ERR_4023	Amount below minimum	Increase the amount or use a different payment method.
ERR_4024	Currency limit reached	The card hit its limit in this currency. Retry later or use a different currency.
ERR_4025	Daily limit reached	Retry after 24 hours or use a different card.
ERR_4026	Monthly limit reached	Retry next month or use a different card.
ERR_4027	Velocity limit exceeded	Declined for high-frequency activity. Wait an hour or use a different payment method.
ERR_4028	Cumulative volume limit reached	Contact support to raise limits.
ERR_4029	Floor limit exceeded	The transaction exceeds your configured floor limit. Contact support if this needs adjustment.
ERR_4030	Issuer unavailable	The issuer is temporarily down. Retry in 30 seconds.
ERR_4031	Issuer timeout	The issuer did not respond in time. Retry in 15 seconds.
ERR_4032	Network route unavailable	No route to the card network right now. Retry in 1 minute.

Fraud signals (4040 to 4048)

Code	Meaning	Typical cause / what to do
ERR_4040	High-risk fraud block	A high-confidence fraud signal blocked the transaction. Do not retry; investigate the customer or order.
ERR_4041	Flagged for review	A medium-confidence signal. Step up to 3DS or verify with the customer before retrying.
ERR_4042	Blocklist match	The card matched a fraud blocklist. Do not retry; treat as confirmed fraud.
ERR_4043	Fraud velocity rule matched	High-frequency activity matched a fraud rule. Wait an hour or step up authentication.
ERR_4044	Geolocation mismatch	The location does not match the card's country of issue. If legitimate, have the customer authenticate via 3DS and retry.
ERR_4045	High device risk	The device scored high for fraud risk. Step up to 3DS or verify the customer's identity.
ERR_4046	High IP risk	The IP address scored high for fraud risk. Step up to 3DS or verify the customer.
ERR_4047	Merchant fraud filter	Your own fraud filter blocked the transaction. Review the filter configuration if this was a false positive.
ERR_4048	Authentication failed in fraud check	Cardholder authentication failed during fraud verification. Retry with a fresh challenge.

Authentication and 3-D Secure (4060 to 4068)

Code	Meaning	Typical cause / what to do
ERR_4060	Authentication required	Strong customer authentication is needed. Initiate a 3DS challenge and retry.
ERR_4061	3DS authentication failed	The cardholder failed the challenge. Ask them to try again or use a different card.
ERR_4062	3DS not supported	The card is not enrolled. The customer should use a different card or contact their issuer to enroll.
ERR_4063	3DS timeout	The cardholder did not complete the challenge in time. Retry the challenge.
ERR_4064	3DS protocol error	A technical issue interrupted authentication. Retry in 30 seconds.
ERR_4065	Issuer authentication unavailable	The issuer's authentication service is down. Retry in 30 seconds.
ERR_4066	Issuer declined authentication	The issuer refused to authenticate the cardholder. The customer should contact their issuer.
ERR_4067	SCA required	Strong Customer Authentication is required under PSD2. Initiate an SCA challenge, typically 3DS2.
ERR_4068	Challenge flow required	Frictionless 3DS is unavailable. Initiate a challenge-flow authentication.

Processing, routing, and async rails (4080 to 4099)

Code	Meaning	Typical cause / what to do
ERR_4080	Temporary error	Retry after a brief delay.
ERR_4081	Processing error	An error occurred while processing. Retry in 30 seconds.
ERR_4082	Processor timeout	The payment processor did not respond in time. Retry in 15 seconds.
ERR_4083	Processor unreachable	The payment processor could not be reached. Retry in 1 minute.
ERR_4084	Service unavailable	The payment service is temporarily unavailable. Retry in 2 minutes.
ERR_4085	Currency not supported on route	Use a different currency or payment method.
ERR_4086	Country not supported	The customer's country is not supported for this transaction. Offer a different payment method.
ERR_4087	Method not supported on route	This payment method is not available on the selected route. Try a different method or contact support.
ERR_4088	Route misconfigured	The payment route has a configuration problem. Contact support.
ERR_4089	Route disabled	The route is currently disabled. Contact support to enable it, or use a different route.
ERR_4090	No route available	No suitable payment route right now. Retry in 1 minute; contact support if persistent.
ERR_4091	Acquirer unreachable	The acquirer network could not be reached. Retry in 1 minute.
ERR_4092	Acquirer declined	The customer should contact their issuer or pay another way.
ERR_4093	Request rejected upstream	The request format was rejected during processing. Contact support; this usually indicates an integration issue.
ERR_4094	Generic decline	The payment was declined without a more specific reason. The customer should contact their issuer or pay another way.
ERR_4095	Underpaid	The customer transferred less than the requested amount (async rails where the customer controls the amount). Reconcile per your policy: refund the partial amount, request the difference, or accept as final.
ERR_4096	Overpaid	The customer transferred more than the requested amount. Refund the difference per your policy.
ERR_4097	Confirmation timeout	The payment was not confirmed within the expected window, including expired async invoices. Ask the customer to start a new payment if still required.
ERR_4098	Payment rail unavailable	The rail itself is temporarily down, for example a network outage or a closed clearing window. Retry in 5 minutes or route through a different method.
ERR_4099	Unclassified decline	Declined for an unspecified reason. Contact support if it persists; the failure will be reviewed and reclassified.

Server and rate limits (ERR_5xxx)

Platform-side failures and throttling. These are safe to retry with the same Idempotency-Key; alert if they persist.

Code	Meaning	Typical cause / what to do
ERR_5003	Upstream timeout	An upstream service timed out. Retry in 15 seconds.
ERR_5004	Database error	A storage operation failed. Retry in 30 seconds; contact support if persistent.
ERR_5005	Upstream unavailable	An upstream service is unavailable. Retry in 1 minute.
ERR_5006	Service not configured	The payment service is not configured for this operation. Contact support; this is a configuration issue.
ERR_5007	Idempotency check timeout	The idempotency check timed out. Retry in 5 seconds with the same key.
ERR_5008	Intent persistence failed	The payment intent could not be persisted. Retry in 30 seconds.
ERR_5009	Audit logging failed	Retry; contact support if persistent.
ERR_5010	Sync failed	A sync operation failed. Retry in 30 seconds.
ERR_5096	Ledger imbalance detected	An internal consistency check failed for this transaction. Contact support with the request identifier.
ERR_5097	Integrity check failed	A data integrity check failed. Retry; contact support if persistent.
ERR_5098	Configuration error	A configuration problem on the account or platform. Contact support.
ERR_5099	Internal error	An unexpected internal error. Retry; contact support if persistent.
ERR_5101	Rate limit exceeded	You exceeded the request rate. Retry after the period in the Retry-After header.
ERR_5102	Quota exceeded	Your account quota was exceeded. Retry after Retry-After, or contact support to raise the quota.
ERR_5103	Sensitive operation rate limited	Sensitive operations carry lower rate limits than general traffic. Wait before retrying.
ERR_5999	Unknown error	An unknown failure, already logged for review. Contact support.

Account policy and compliance (ERR_6xxx)

Account-level policy gates: verification, blocklists, uploads, and compliance records.

Code	Meaning	Typical cause / what to do
ERR_6001	KYB required	Business verification must complete before this operation. Complete KYB from the dashboard.
ERR_6002	KYB pending	Verification is under review. Wait; contact support if pending more than 5 business days.
ERR_6003	Blocklisted	The entity is on a blocklist. Contact support to dispute the entry.
ERR_6004	Velocity limit exceeded	An account velocity limit was hit. Wait before retrying, or contact support to raise the limit.
ERR_6005	File too large	The uploaded file exceeds the size limit. Reduce it and re-upload.
ERR_6006	Invalid file type	The file type is not permitted. Re-upload using a supported type.
ERR_6101	Compliance certificate not found	The certificate identifier does not resolve. Verify it.
ERR_6102	Invalid certificate type	Use a supported certificate type from the API reference.
ERR_6103	Invalid certificate state transition	The certificate cannot move to the requested state. Check its current state.
ERR_6104	Certificate expired	The certificate is expired or its dates are invalid. Renew or correct the dates.
ERR_6105	Duplicate compliance record	A matching record already exists. Use it or modify the request.
ERR_6106	Certificate validation failed	Review the certificate fields against the API reference.

---

TensorRail, Limassol, Cyprus.