Errors
HTTP Status Codes
What each HTTP status code means in the OuiPay API and how to handle it.
Error shape
Every non-2xx response uses the same envelope:
{
"error": {
"code": "INSUFFICIENT_FUNDS",
"message": "The wallet balance is insufficient for this payment.",
"request_id": "OUI-REQ-01M2S18..."
}
}code: machine-readable, stable. Branch on this, never onmessage.message: human-readable, may change. Safe to display to operators, not for programmatic handling.request_id: quote it to support. It traces the request end to end.
Status code reference
| Status | Category | Meaning | Your action |
|---|---|---|---|
200 | Success | Request succeeded | Process the response |
201 | Created | Resource created | Process the response |
400 | Validation | Invalid field or malformed request | Fix the request |
401 | Authentication | Missing, malformed, or revoked API key | Fix the key |
403 | Authorization / policy | Valid key, disallowed IP, scope, or PIN needed | Check scope, IP, or prompt PIN |
404 | Not found | Resource does not exist | Check the id |
409 | Conflict | Duplicate or invalid state transition | Check current state |
422 | Business rule violation | Funds, limits, compliance, or method issue | Read error.code, act |
429 | Rate limited | Too many requests | Back off, retry later |
500 | Internal error | OuiPay infrastructure issue | Retry; quote request_id |
502 | Provider error | Upstream payment provider failed | Retry-safe via idempotency |
A 4xx is still a transaction
A failed attempt leaves a failed transaction entry: with status: "failed",
failure.code, and failure.stage recording where it stopped. Query it:
curl https://api.ouipay.com/v1/transactions/01M2S18... \
-H "Authorization: Bearer sk_test_..."This means a rejected payment is never "lost": it is on record, with the exact reason.
Retrying safely
5xx/ timeout: retry with the sameIdempotency-Key. The original response returns; you cannot double-charge.4xxbusiness rule: do not retry; the failure is final for that request. Fix the cause (insufficient funds, limit, compliance) and submit a new request with a new idempotency key.unknownstatus: never retry. Wait for the webhook or poll status; the outcome is being reconciled.