Errors
One envelope, stable machine-readable codes, honest messages.
{ "error": { "code": "insufficient_funds", "message": "The partner balance cannot cover this amount plus fees." } }Codes
| HTTP | Code | Meaning |
|---|---|---|
| 400 | validation_error | A field is missing or malformed — the message says which. |
| 400 | idempotency_key_required | Money-moving POST without an Idempotency-Key header. |
| 401 | invalid_api_key | Unknown, revoked, or malformed key. |
| 402 | insufficient_funds | Your balance can't cover the amount plus fees. Fund and retry. |
| 402 | provider_declined | The card network declined the operation. |
| 403 | partner_suspended | Your account is suspended — contact PrimCard. |
| 403 | secure_details_disabled | Card-detail access isn't enabled for your account. |
| 403 | test_key_not_allowed / live_key_not_allowed | Endpoint exists only in the other mode. |
| 404 | card_not_found | No such card on this account (ids from the other mode 404 too). |
| 409 | external_ref_taken | You already created a card under this external_ref — GET it instead. |
| 409 | invalid_state | The card's current status doesn't allow this (e.g. topping up a frozen card). |
| 409 | idempotency_in_flight | Original request still processing — retry the same key shortly. |
| 422 | limit_exceeded | A platform limit (per-transaction / velocity / card cap) blocks this. |
| 422 | idempotency_conflict | Same Idempotency-Key, different body. |
| 429 | rate_limited | Slow down; honor Retry-After. |
| 500 | internal_error | Our side. For money POSTs: retry with the same Idempotency-Key. |
Rule of thumb: 4xx means fix the request (retrying unchanged won't help); 5xx or a network timeout means retry with the same Idempotency-Key.