Guides

Errors

Errors use conventional HTTP status codes and a consistent JSON body with a stable, machine-readable code.

Error body

{
  "error": {
    "type": "invalid_request",
    "code": "validation_error",
    "message": "amount: Amounts must be greater than zero.",
    "param": "amount",
    "request_id": "req_8f1c2b7d9a3e4f50"
  }
}

code is stable — branch on it, not on message.
param is present when a specific field caused the error.
request_id identifies the request in your request logs and for support.
Errors never include stack traces, SQL, or credentials.

Error codes

validation_errorHTTP 400invalid_request

The request body, query or headers failed validation. param points at the first invalid field.

invalid_jsonHTTP 400invalid_request

The request body is not valid JSON.

idempotency_key_requiredHTTP 400invalid_request

This endpoint can create side effects and requires an Idempotency-Key header.

product_unavailableHTTP 400invalid_request

The requested card product is not available through the API for this environment.

authentication_requiredHTTP 401authentication_error

No credentials were supplied. Send Authorization: Bearer <api key>.

invalid_api_keyHTTP 401authentication_error

The API key is unknown, revoked or expired.

environment_mismatchHTTP 401authentication_error

The API key belongs to a different environment than the base URL you called. Sandbox keys (gs_test_) only work against the Sandbox base URL, Live keys (gs_live_) only against the Live base URL.

insufficient_fundsHTTP 402transfer_error

The wallet's available balance is lower than the amount plus fees.

insufficient_scopeHTTP 403permission_error

The API key does not have the scope required for this endpoint.

live_access_not_approvedHTTP 403permission_error

The organization has not been approved for Live access.

sandbox_onlyHTTP 403permission_error

This endpoint only exists in the Sandbox environment.

activation_requiredHTTP 403permission_error

Live card programs require an activated account (business verification and setup fee).

not_foundHTTP 404invalid_request

The requested resource does not exist or is not visible to this API key.

card_state_conflictHTTP 409card_error

The operation is not allowed in the card's current state (for example funding a frozen or terminated card, or terminating a card that still has a balance).

operation_in_progressHTTP 409card_error

Another operation on this card is still being processed. Retry shortly.

insufficient_card_balanceHTTP 409card_error

The card balance is too low for this withdrawal. A minimum balance must remain on the card.

idempotency_in_progressHTTP 409idempotency_error

A request with the same Idempotency-Key is still being processed. Retry later.

payload_too_largeHTTP 413invalid_request

The request body exceeds the maximum allowed size.

unsupported_media_typeHTTP 415invalid_request

Request bodies must be sent as application/json.

idempotency_key_reuseHTTP 422idempotency_error

The Idempotency-Key was already used with a different request body or endpoint.

rate_limitedHTTP 429rate_limit_error

Too many requests. Wait for the number of seconds in the Retry-After header.

internal_errorHTTP 500api_error

An unexpected error occurred. The request_id identifies the failure for support.

provider_errorHTTP 502provider_error

The downstream provider returned an error. The transfer was marked as failed and reserved funds were released.

live_operations_disabledHTTP 503service_unavailable

Live money movement is not enabled on this deployment. No provider has been authorized yet.

provider_not_configuredHTTP 503service_unavailable

No payment provider is configured for this environment and operation.

provider_timeoutHTTP 504provider_error

The downstream provider did not answer in time. The transfer was marked as failed and reserved funds were released.