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 number with at most two decimal places",
"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 | null | Optional extra context. |
When you contact support, include the endpoint, your externalId, and the full error envelope — that's enough for us to pull the request and provider trace on our side.
Code reference
| HTTP | Code | When it fires |
|---|---|---|
| 400 | invalid_argument | Generic validation failure — payload shape, missing field, bad enum |
| 400 | invalid_argument | Amount is zero, negative, or has sub-cent precision |
| 400 | invalid_argument | invalidCurrency: currency is not in the supported list |
| 400 | invalid_argument | Card token unknown, inactive, or expired |
| 400 | invalid_argument | Refund amount exceeds the refundable balance |
| 400 | failed_precondition | Payment not refundable in its current state |
| 400 | failed_precondition | A previous refund on this payment is still processing |
| 401 | unauthenticated | Missing, malformed, or revoked API credentials |
| 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-identified resource already exists |
| 409 | aborted | Payment or refund processing failed at the provider — including provider-side errors. The request was valid but the outcome wasn't success |
| 503 | unavailable | The provider couldn't be reached at all (network failure) — safe to retry with the same externalId |
| 500 | internal | No active payment provider configured, or an unexpected server error |
Codes are coarse — the message disambiguates
The code values are the framework's standard error codes, so one code can
cover several situations (everything under invalid_argument, for example).
Use the message to disambiguate in logs and support tickets, but design your
flow so the code alone is sufficient to branch on.
What 409 aborted means
aborted is the "clean failure" outcome: the request was processed but the
charge or refund did not go through at the provider. Treat it as "the payment
did not happen — read the message to know why", not as a bug in your request.
What to log
For every error response, log at minimum:
error.codeerror.message- The endpoint, your
externalId, 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.