Concepts
Errors
Status codes and how to handle them.
We use ordinary HTTP status codes. An error answer has the same envelope as a success, with success: false and a message written for a person. Show it in your logs; it usually says exactly what to change.
An error · test
{
"success": false,
"message": "Row 1: (a short sentence saying what is wrong with that payment)",
"code": 400
}| Status | Meaning | What to do |
|---|---|---|
| 400 | The request is not valid, or the Idempotency-Key is missing. | Fix the request. It is not stored, so you can resend it with the same key. |
| 401 | No token, a bad token, or the credentials were revoked. | Get a new token. If that fails, check the credentials. |
| 403 | The token lacks the scope, or the business may not do this yet. | Ask for the scope, or finish the business review. |
| 404 | Not found, or not yours. | Check the id. Also what live credentials get from test-only calls. |
| 409 | The thing is in the wrong state, or a key clashes. | Fetch it and look at its status; do not blindly retry. |
| 429 | Too many requests. | Wait for the time in the Retry-After header, then try again. |
| 5xx | Something went wrong on our side. | Retry with the same Idempotency-Key, waiting a little longer each time. |