Skip to main content

Read an error

When a request fails, the HTTP status tells you the type of failure. The response usually includes a code and a message:
Use the HTTP status and code in your application logic. The message explains the problem, but its wording can change. Some errors also include details, such as the minimum and maximum amount allowed. Successful responses usually contain status: "success" and data. Check each endpoint for its exact response.

Common errors

Endpoints may return additional codes. Handle unrecognised codes as errors using the HTTP status.

Fix a missing or invalid field

A missing or invalid field usually returns 400 BAD_REQUEST. For example, a transfer request without quoteId returns:
Add the missing field and check the rest of your request. A message such as payOut.recipientId is required. points to recipientId inside payOut. For POST /v1/wallets, 400 BAD_REQUEST with details.reason: "unsupported_asset_network" means the asset and network pair is not supported for a new deposit address. Select a pair from GET /v1/wallets/options before trying again. 503 PROVIDER_UNAVAILABLE means setup is temporarily unavailable; follow the retry guide with the original key and body.

Understand quote errors

These examples use fictional amounts. Read the values in your own response for the limits that apply to your business.

No conversion price

A quote can return 404 when a price is unavailable:

Amount outside the conversion limits

A quote can return 422 when the amount you want to convert is too small or too large:
This limit applies to the source amount you are converting. A payout method’s limit applies to the destination amount being sent. Business payout allowances are measured in USD equivalent. See Limits for the difference.

Not enough available funds

A quote can return 409 when your available source balance is too low:
Check the amount and all fees against your available balance.

Retry after a failure

For temporary read failures, wait before trying again and increase the delay after repeated failures. A timeout or 5xx response on a write does not mean the request failed. It may already have been processed. Keep the original request identifiers and use the retry rules to check or recover the result before creating another payment.

Request IDs

Every API response includes an x-request-id header. Save this ID when a request fails so support can locate it. You can also send your own x-request-id. Use 8–128 characters containing only letters, digits, ., _, : or -. Ledig keeps a valid ID and generates one if it is missing or invalid. When contacting support, include:
  • The request ID and approximate time.
  • Sandbox or Live.
  • The HTTP method and endpoint, such as GET /v1/balances/USD.
  • The HTTP status and error code.
Do not include API keys, secrets, signatures or customer documents.

Troubleshooting checklist

  1. Check that your API URL and credentials belong to the same environment.
  2. Use the current Unix timestamp in seconds and keep your server clock in sync.
  3. Sign the exact method, path, query string and body you send.
  4. Check the API key’s required permissions.
  5. If acting for a managed business, use HMAC v2 and the correct business-selection headers.
  6. Contact support@ledig.io with the request ID if you need help.