> For the complete documentation index, see [llms.txt](https://docs.ledig.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ledig.io/errors/errors-and-troubleshooting.md).

# 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:

```json
{
  "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

```json
{
  "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.