Errors
Every error MintCash can return, what it means, and the HTTP status code it carries. The full taxonomy in one place.
When something goes wrong, MintCash responds with a consistent envelope and a machine-readable code you can branch on. No string-matching, no parsing English.
Error envelope
{
"code": "invalid_argument",
"message": "amount must be a positive integer in cents",
"details": {
"requestId": "req_01HXX..."
}
}| Field | Type | Notes |
|---|---|---|
code | string | Machine-readable. Stable across versions — safe to branch on. |
message | string | Human-readable. May change wording — never branch on this. |
details | object | Optional context. Always includes requestId for log correlation. |
Include the requestId when you contact support — we can pull the full request, response, and provider trace from a single ID.
Code reference
| HTTP | Code | When it fires |
|---|---|---|
| 400 | invalid_argument | Generic validation failure — payload shape, missing field, bad enum |
| 400 | invalid_argument | invalidAmount: amount is zero, negative, or has sub-cent precision |
| 400 | invalid_argument | invalidCurrency: currency is not in the supported list |
| 400 | invalid_argument | invalidCardToken: token unknown, inactive, expired or wrong |
| 401 | unauthenticated | Missing, malformed, or revoked API credentials |
| 401 | unauthenticated | Webhook signature failed HMAC verification |
| 403 | permission_denied | Request IP is not on the key's allow list |
| 403 | permission_denied | Merchant account is deactivated |
| 404 | not_found | The resource (payment, subscription, refund) doesn't exist |
| 409 | already_exists | A uniquely-named resource already exists (e.g. a customer email). |
| 499 | aborted | paymentDeclined: provider rejected (insufficient funds, AVS/CVV) |
| 499 | aborted | paymentFailed: provider-level failure that isn't a clean decline |
| 503 | unavailable | providerUnreachable: provider returned 5xx or network call failed |
| 500 | internal | providerNotConfigured: no active PSPs for this account |
Why 499?
HTTP 499 is "Client Closed Request" in our framework's default mapping. We use it for clean payment-level failures (declined, failed) where the request was processed but the outcome wasn't success. Treat 499 as "the payment did not happen. Read the body to know why."
What to log
For every error response, log at minimum:
error.codeerror.messageerror.details.requestId- The endpoint and the request payload (redact card tokens)
That's enough for us to find the failure on our side and for you to correlate against your application logs.