Errors & Troubleshooting

The Ledig Technologies API returns errors as JSON objects in a standardized format. This ensures that your integration can reliably parse and handle issues.

---

Error Format

Every error response follows this structure:

{
  "error": {
    "code": "<string>",
    "message": "<human-readable>"
  }
}

Fields

• code → A machine‑readable string identifying the error type.

• message → A human‑readable explanation of what went wrong.

---

Example

{
  "error": {
    "code": "auth_missing",
    "message": "Missing authentication headers"
  }
}

---

Common Error Codes

Code	Meaning	When it occurs
auth_missing	Missing authentication headers	One or more of x-ledig-key, x-ledig-timestamp, or x-ledig-signature was not included in the request
auth_invalid_key	Invalid API key	The provided x-ledig-key does not exist in our records
auth_corrupt_record	Corrupted API key record	The key record could not be parsed on our side (contact support if persistent)
auth_inactive	API key inactive	The key exists but is not marked as active
auth_bad_signature	Signature mismatch	The calculated signature does not match. Usually due to incorrect payload formatting or a bad secret
forbidden	Scope missing	The key is valid but lacks the required permission for this endpoint
not_found	Endpoint not found	The request path does not match any existing endpoint
ledig_error	Internal/Upstream error	Something went wrong on Ledig’s side or an upstream provider failed

---

Troubleshooting Tips

1. Authentication errors

   • Double‑check that all three headers (x-ledig-key, x-ledig-timestamp, x-ledig-signature) are present.

   • Confirm your timestamp is a current Unix time in seconds.

   • Make sure you are signing the payload as: timestamp.METHOD.path.body (with body empty for GET).

2. Scope errors

   • Review the scopes attached to your API key.

   • If you need additional scopes (instant, fiat_wallet, crypto_wallets), generate a new key in Settings → API & Webhooks.

3. 404 errors

   • Check that you are calling the endpoint under /v1/.

   • Confirm you are using the correct environment: https://sandbox.ledig.io/v1 or https://api.ledig.io/v1.

4. 500 or ledig_error

   • These are usually transient. Retry with exponential backoff.

   • If persistent, contact Ledig support with the request_id header (if provided) and payload details.

---

Best Practices for Error Handling

• Log every error with both code and message.

• Retry cautiously: only retry for ledig_error or network failures, not for forbidden or auth_* errors.

• Fail gracefully: surface clear messages in your UI when an operation is blocked by permissions.

• Use idempotency when retrying writes (e.g., conversions, payouts) to avoid duplicates.