GTRADEDocs
Reference

Errors

The API uses HTTP status codes and a consistent JSON error body with a machine-readable code.

#Error format

json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "customer_email must be a valid email address.",
    "request_id": "req_ba5e76a81fab6fdd"
  }
}
FieldDescription
typeBroad category: invalid_request_error, authentication_error, idempotency_error, rate_limit_error or api_error.
codeSpecific, stable code. Branch on this in your code.
messageHuman-readable explanation. It may change; don't parse it.
request_idSame as the X-Request-Id response header. Include it when you contact support.

#Error codes

HTTPtypecodeMeaningWhat to do
400invalid_request_errorinvalid_jsonThe body is not a JSON object.Fix the request body.
400invalid_request_errorparameter_invalidBad query parameter (limit, status, starting_after).Fix the parameter.
401authentication_errorinvalid_api_keyMissing or unknown API key.Check the key and header. See Authentication.
404invalid_request_errorpayment_not_foundUnknown payment id, or a payment of another account.Check the id and the API key used.
404invalid_request_errorwebhook_not_foundUnknown webhook endpoint id.List your endpoints.
404invalid_request_errorroute_not_foundUnknown path.Check the URL.
405invalid_request_errormethod_not_allowedKnown path, wrong HTTP method.Check the method.
409idempotency_erroridempotency_key_reusedThe key was already used with different parameters.Use a new key for a new payment.
409idempotency_erroridempotency_key_in_useA request with this key is still running.Retry after a moment with the same key.
413invalid_request_errorbody_too_largeThe body exceeds 64 KB.Send less data (check metadata).
422invalid_request_errorparameter_missingA required field is missing.Add the field named in message.
422invalid_request_errorparameter_invalidA field has an invalid value.Fix the field named in message.
422invalid_request_errorpayment_rejectedThe payment could not be created with these parameters.Check the amount and email; contact support if it persists.
422invalid_request_errorwebhook_limit_reachedYou already have 10 webhook endpoints.Delete one first.
429rate_limit_errorrate_limitedToo many requests.Wait Retry-After seconds. See Rate limits.
500api_errorinternal_error, upstream_error, webhook_setup_failedTemporary problem on our side.Retry with backoff, using the same idempotency key.

#Handling errors

  • 4xx (except 409 idempotency_key_in_use and 429): your request needs to change. Don't retry it unchanged.
  • 409 idempotency_key_in_use, 429 and 5xx: retry with exponential backoff. For POST /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_id with every error.

The SDKs do all of this for you and raise typed errors.

#Example: a bad request

bash
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"}'
json
{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"customer_email must be a valid email address.","request_id":"req_ba5e76a81fab6fdd"}}