See Error concepts for how to handle errors idiomatically. This page is the complete code table.
Error envelope
{
"error": {
"type": "validation_error",
"code": "email_invalid",
"message": "...",
"param": "email",
"requestId": "req_01HX3ZE..."
}
}
By status code
400 validation_error
code | Meaning |
|---|
field_required | Required field missing. See param. |
field_too_long | param exceeded max length. |
field_too_short | param below min length. |
enum_invalid | param isn’t an allowed value. |
email_invalid | Not a valid email. |
phone_invalid | Not a valid E.164 phone. |
url_invalid | Not a valid URL. |
currency_invalid | Unsupported currency code. |
amount_too_small | Below minimum charge amount. |
amount_too_large | Above maximum allowed for this tier. |
idempotency_key_reuse | Key used with a different body. |
idempotency_key_conflict | Key in use by a concurrent request. |
cursor_expired | Pagination cursor older than 24 hours. |
401 authentication_error
code | Meaning |
|---|
key_missing | Missing x-api-key or x-api-secret. |
key_invalid | Key pair not recognized. |
key_revoked | Key pair was revoked. |
signature_invalid | Webhook signature check failed. |
403 permission_error
code | Meaning |
|---|
key_forbidden | Key lacks the required scope. |
tenant_suspended | Tenant has been suspended. |
feature_not_enabled | Feature (e.g., payments) isn’t enabled on this tenant. |
404 not_found
code | Meaning |
|---|
resource_not_found | No object with that ID visible to this tenant. |
409 conflict
code | Meaning |
|---|
duplicate_email | User with this email already exists. |
kyc_already_completed | KYC is finalized. |
transaction_not_pending | Transaction is past the point of this action. |
invite_already_accepted | Invite token has been consumed. |
429 rate_limit_error
code | Meaning |
|---|
rate_limit_exceeded | Honor Retry-After. |
5xx api_error
code | Meaning |
|---|
internal_error | Unexpected Geldstuck-side error. Retry with backoff. |
upstream_error | A dependent service is degraded. Retry with backoff. |
service_unavailable | Brief outage. Retry with backoff. |
When filing a support ticket, include the x-request-id header value from the failing response - it uniquely identifies the request across all our logs.
