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 | missingReturnUrl: HPP charge without a returnUrl |
| 400 | invalid_argument | invalidCardToken: token unknown, inactive, expired, or for another merchant |
| 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 or isn't yours |
| 409 | already_exists | Duplicate creation attempt — externalId collision with a different payload |
| 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 provider for this merchant |
| 500 | internal | databaseUnreachable: our database is down — we'll be paging |
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.