> ## Documentation Index
> Fetch the complete documentation index at: https://docs.globalstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Error reference

> Every error code the GlobalStack API can return, with HTTP status, common causes, and how to resolve it.

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.

```json theme={null}
{
  "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"
    }
  }
}
```

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

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](/api-reference/failure-reasons).

<h2 id="bad_request">
  Bad request
</h2>

**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.

<h2 id="invalid_input">
  Invalid input
</h2>

**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.

**What to do** — Inspect the request payload for missing or malformed fields and retry.

<h2 id="invalid_amount_precision">
  Invalid amount precision
</h2>

**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.

<h2 id="prohibited_country">
  Prohibited country
</h2>

**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.

<h2 id="account_resolution_failed">
  Account resolution failed
</h2>

**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.

<h2 id="authentication_failed">
  Authentication failed
</h2>

**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.

<h2 id="merchant_inactive">
  Merchant inactive
</h2>

**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.

<h2 id="forbidden">
  Forbidden
</h2>

**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.

<h2 id="forbidden_key_role">
  Forbidden key role
</h2>

**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.

<h2 id="resource_access_required">
  Resource access required
</h2>

**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.

<h2 id="not_found">
  Not found
</h2>

**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.

<h2 id="invalid_status">
  Invalid status
</h2>

**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.

<h2 id="conflict">
  Conflict
</h2>

**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.

<h2 id="duplicate_resource">
  Duplicate resource
</h2>

**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.

<h2 id="idempotency_conflict">
  Idempotency conflict
</h2>

**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.

<h2 id="idempotency_in_progress">
  Idempotency in progress
</h2>

**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.

<h2 id="api_key_limit_exceeded">
  API key limit exceeded
</h2>

**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.

<h2 id="access_already_granted">
  Access already granted
</h2>

**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.

<h2 id="ledger_insufficient_funds">
  Ledger insufficient funds
</h2>

**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.

<h2 id="rate_limited">
  Rate limited
</h2>

**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.

<h2 id="internal_error">
  Internal error
</h2>

**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.