Error reference - GlobalStack API

Every API response — success or failure — uses the same envelope. On failure, status is false, data is null, code is a stable machine-readable error code, and meta.next_steps carries an action and a docs_url that links straight to this page at the matching anchor.

{
  "status": false,
  "message": "Human-readable explanation for developers and logs.",
  "code": "bad_request",
  "data": null,
  "meta": {
    "request_id": "req_01ABC...",
    "timestamp": "2026-04-22T02:00:00Z",
    "version": "1",
    "next_steps": {
      "action": "Review the request and retry with corrected parameters.",
      "docs_url": "https://docs.globalstack.io/errors#bad_request"
    }
  }
}

message is for developers and logs — do not show it to end users. Quote meta.request_id when contacting support.

These are request-level errors — the API call itself was rejected. If a call succeeds but the resulting money movement or verification later ends in a failed state, the reason is reported on the resource’s failure_reason field instead — see Failure reasons.

Bad request

HTTP 400 · bad_request The request failed validation — a required field is missing, or a value has the wrong type or format. Common causes

A required field was omitted from the request body.
A field has the wrong type (e.g. a string where a number is expected).
A value fails a format or enum constraint. The meta.errors array lists the offending fields.

What to do — Review the request and retry with corrected parameters.

Invalid input

HTTP 400 · invalid_input A field passed schema validation but failed a semantic check the API applies before processing. Common causes

A value is individually valid but invalid in context (e.g. an amount below the minimum, or mismatched currency pair).
A referenced field combination isn’t permitted.
A South African account_number that cannot belong to the chosen bank — wrong number of digits, or any character that isn’t a digit. See South African account numbers below.

What to do — Inspect the request payload for missing or malformed fields and retry. The message is specific and safe to show to the person who entered the value.

South African account numbers

ZAR bank account numbers are checked structurally before a beneficiary is saved and again when an offramp quote is created. The check is local — it answers “could this number belong to this bank?” and nothing more. It cannot tell you whether the account exists, is open, or accepts credits. Digits only. Spaces, dashes and every other separator are rejected rather than stripped. 6200-4626-662 and " 62004626662 " are both invalid, even though removing the punctuation would leave a valid number — we never alter what you send, so a number we accept is exactly the number we pay. Length depends on the bank, taken from the account_provider on the beneficiary:

Bank	Digits
FNB / RMB	11
Capitec	10
Nedbank	10
Standard Bank	9 or 11
Investec	11
TymeBank	11
Discovery	11
Bank Zero	11
African Bank	11
Absa	8, 9, 10 or 11

Any other South African bank is checked against the general range of 8 to 11 digits. The message names the bank and both counts — FNB accounts are 11 digits; this account number has 10. — so it can be surfaced directly to whoever is entering the details. Two cases worth knowing about:

PayShap beneficiaries are not affected. On the payshap rail, account_number is a proxy — a mobile number in E.164 form, or a ShapName such as acme@nedbank — so none of the rules above apply to it.
An existing beneficiary can fail at quote time. Beneficiaries saved before this check existed are validated the first time you quote against them, so POST /v1/quotes can return this error for a beneficiary that saved cleanly months ago. Update the beneficiary’s account_number and quote again.

Invalid amount precision

HTTP 400 · invalid_amount_precision The amount carries more decimal places than the currency can settle. USDC settles in whole US cents, so USDC amounts support at most 2 significant decimal places. Trailing zeros are fine — 2.980000 is accepted, 2.980228 is rejected. Common causes

A high-precision USDC source_amount or amount on an offramp quote, conversion quote, or transfer — for example a 6-decimal value taken directly from a balance or a destination-anchored price calculation.

What to do — The amount has more decimal places than the currency can settle. Reduce it to the stated maximum (e.g. 2 decimal places for USDC — trailing zeros are fine) and retry.

Prohibited country

HTTP 400 · prohibited_country The country_code supplied is on GlobalStack’s compliance prohibited list, so the merchant or customer cannot be onboarded from it. Onboarding is open to all other countries; this is a presence restriction only — it does not limit which currencies or corridors an onboarded merchant can transact in. Common causes

Registering a merchant or creating a customer with a country_code on the prohibited list.
A typo producing a prohibited ISO code. (A value that isn’t a valid ISO-3166-1 alpha-2 code at all returns invalid_input instead.)

What to do — This country is not available for onboarding.

Account resolution failed

HTTP 400 · account_resolution_failed The bank account could not be verified with the provider. Common causes

The account_number is wrong or doesn’t exist at the named institution.
The provider_id (bank/institution) doesn’t match the account.

What to do — The account could not be verified with the provider. Confirm the account_number and provider_id and retry.

Authentication failed

HTTP 401 · authentication_failed The request was not authenticated. Common causes

Missing Authorization header.
An invalid, revoked, or malformed API key / bearer token.
Using a key from the wrong environment.

What to do — Include a valid Bearer token in the Authorization header.

Merchant inactive

HTTP 401 · merchant_inactive The merchant account is authenticated but not yet active. Common causes

KYC/KYB verification is not complete.
The account is pending review.

What to do — This merchant account is not active yet. Please follow the KYC link provided to complete identity verification (KYC/KYB) to activate it.

Forbidden

HTTP 403 · forbidden The credentials are valid but don’t grant access to this resource. Common causes

The API key or user lacks permission for the resource.
Accessing a resource that belongs to another merchant.

What to do — The credentials supplied do not have access to this resource.

Forbidden key role

HTTP 403 · forbidden_key_role The requested API-key role isn’t permitted for this caller. Common causes

Creating or granting a key with a role above the caller’s own grant.

What to do — The requested API-key role is not permitted under this user or integration. Use a role at or below the caller’s own grant.

Resource access required

HTTP 403 · resource_access_required The resource requires an explicit access grant the caller doesn’t have yet. Common causes

Using a resource (e.g. a currency) that is gated behind an access request.

What to do — This resource requires explicit access. Request it via POST /v1/currencies/:code/access-requests and retry after approval.

Not found

HTTP 404 · not_found The referenced resource doesn’t exist. Common causes

A wrong, mistyped, or already-deleted resource id in the path.
The resource belongs to a different merchant account.

What to do — Verify the resource identifier and retry.

Invalid status

HTTP 409 · invalid_status The action isn’t allowed while the resource is in its current state. Common causes

Acting on a resource whose lifecycle has moved past the point the action is valid (e.g. cancelling an already-settled transfer).

What to do — Check the resource status and ensure the action is permitted in its current state.

Conflict

HTTP 409 · conflict The request conflicts with the current state of the resource. Common causes

A concurrent update changed the resource since you last read it.

What to do — The request conflicts with the current state of the resource. Refresh and retry.

Duplicate resource

HTTP 409 · duplicate_resource A resource with the same unique value already exists. Common causes

Re-using a value that must be unique (e.g. a reference or a beneficiary already on file).

What to do — A resource with the same unique identifier already exists. Retry with different values.

Idempotency conflict

HTTP 409 · idempotency_conflict The Idempotency-Key was already used with a different request body. Common causes

Reusing an idempotency key for a request whose body differs from the original.

What to do — The Idempotency-Key has already been used with a different request body. Use a new key, or replay the request with the original body.

Idempotency in progress

HTTP 409 · idempotency_in_progress A request with the same Idempotency-Key is still being processed. Common causes

A retry fired while the original request with that key is still in flight.

What to do — A request with the same Idempotency-Key is still in progress. Retry after a short delay.

API key limit exceeded

HTTP 409 · api_key_limit_exceeded The account has reached its maximum number of active API keys. Common causes

Creating a new key while at the active-key cap.

What to do — Revoke an unused API key before creating a new one.

Access already granted

HTTP 409 · access_already_granted The merchant already has an active grant for the resource. Common causes

Submitting an access request for a resource that’s already granted.

What to do — This merchant already has an active grant for the resource. No further action is required.

Ledger insufficient funds

HTTP 422 · ledger_insufficient_funds The source balance doesn’t have enough available funds. Common causes

The wallet’s available balance is below the requested amount (funds may be held/pending).

What to do — The source balance does not have enough available funds for this amount. Fund the wallet or lower the amount and retry.

Rate limited

HTTP 429 · rate_limited You’ve exceeded the request rate limit. Common causes

Too many requests in a short window.

What to do — You have exceeded the request rate limit. Slow down and retry shortly.

Internal error

HTTP 500 · internal_error An unexpected server error occurred. Common causes

An unhandled condition on the server.

What to do — Retry the request after a short delay. If the failure persists, contact support.

Upstream service unavailable

HTTP 500 · external_service_unavailable An upstream service required to complete the request was unavailable or rejected the request. The failure detail is recorded on our side and never returned in the response. Common causes

A transient upstream outage, timeout, or rejection while fulfilling the request (for example, while creating a deposit credential).

What to do — The request was not completed. Retry after a short delay; if the failure persists, contact support.

Configuration error

HTTP 500 · configuration_error The service is misconfigured for the requested operation. This is a deploy-time issue on our side, not something the caller can fix. Common causes

A required server-side configuration value is missing or invalid in the current environment.

What to do — Nothing on your end resolves this. Contact support with the request_id if it persists.

​Bad request

​Invalid input

​South African account numbers

​Invalid amount precision

​Prohibited country

​Account resolution failed

​Authentication failed

​Merchant inactive

​Forbidden

​Forbidden key role

​Resource access required

​Not found

​Invalid status

​Conflict

​Duplicate resource

​Idempotency conflict

​Idempotency in progress

​API key limit exceeded

​Access already granted

​Ledger insufficient funds

​Rate limited

​Internal error

​Upstream service unavailable

​Configuration error

Bad request

Invalid input

South African account numbers

Invalid amount precision

Prohibited country

Account resolution failed

Authentication failed

Merchant inactive

Forbidden

Forbidden key role

Resource access required

Not found

Invalid status

Conflict

Duplicate resource

Idempotency conflict

Idempotency in progress

API key limit exceeded

Access already granted

Ledger insufficient funds

Rate limited

Internal error

Upstream service unavailable

Configuration error