Reference
Errors
The API uses HTTP status codes and a consistent JSON error body with a machine-readable code.
#Error format
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "customer_email must be a valid email address.",
"request_id": "req_ba5e76a81fab6fdd"
}
}| Field | Description |
|---|---|
type | Broad category: invalid_request_error, authentication_error, idempotency_error, rate_limit_error or api_error. |
code | Specific, stable code. Branch on this in your code. |
message | Human-readable explanation. It may change; don't parse it. |
request_id | Same as the X-Request-Id response header. Include it when you contact support. |
#Error codes
| HTTP | type | code | Meaning | What to do |
|---|---|---|---|---|
| 400 | invalid_request_error | invalid_json | The body is not a JSON object. | Fix the request body. |
| 400 | invalid_request_error | parameter_invalid | Bad query parameter (limit, status, starting_after). | Fix the parameter. |
| 401 | authentication_error | invalid_api_key | Missing or unknown API key. | Check the key and header. See Authentication. |
| 404 | invalid_request_error | payment_not_found | Unknown payment id, or a payment of another account. | Check the id and the API key used. |
| 404 | invalid_request_error | webhook_not_found | Unknown webhook endpoint id. | List your endpoints. |
| 404 | invalid_request_error | route_not_found | Unknown path. | Check the URL. |
| 405 | invalid_request_error | method_not_allowed | Known path, wrong HTTP method. | Check the method. |
| 409 | idempotency_error | idempotency_key_reused | The key was already used with different parameters. | Use a new key for a new payment. |
| 409 | idempotency_error | idempotency_key_in_use | A request with this key is still running. | Retry after a moment with the same key. |
| 413 | invalid_request_error | body_too_large | The body exceeds 64 KB. | Send less data (check metadata). |
| 422 | invalid_request_error | parameter_missing | A required field is missing. | Add the field named in message. |
| 422 | invalid_request_error | parameter_invalid | A field has an invalid value. | Fix the field named in message. |
| 422 | invalid_request_error | payment_rejected | The payment could not be created with these parameters. | Check the amount and email; contact support if it persists. |
| 422 | invalid_request_error | webhook_limit_reached | You already have 10 webhook endpoints. | Delete one first. |
| 429 | rate_limit_error | rate_limited | Too many requests. | Wait Retry-After seconds. See Rate limits. |
| 500 | api_error | internal_error, upstream_error, webhook_setup_failed | Temporary problem on our side. | Retry with backoff, using the same idempotency key. |
#Handling errors
- 4xx (except
409 idempotency_key_in_useand429): your request needs to change. Don't retry it unchanged. - 409
idempotency_key_in_use, 429 and 5xx: retry with exponential backoff. ForPOST /v1/payments, always retry with the same idempotency key, so a payment created by the first attempt is returned instead of duplicated. - Network errors and timeouts: the request may or may not have been processed. Retry with the same idempotency key.
- Log
request_idwith every error.
The SDKs do all of this for you and raise typed errors.
#Example: a bad request
curl -s https://api.gtradegateway.io/v1/payments \
-H "Authorization: Bearer $GTRADE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount_usd": 25, "customer_email": "not-an-email"}'{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"customer_email must be a valid email address.","request_id":"req_ba5e76a81fab6fdd"}}