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

# Error Handling

> Error codes and troubleshooting for Core API

## Error Handling

Core API uses standard HTTP status codes. Error responses have this shape:

```json theme={null}
{
  "error": "ERROR_CODE",
  "message": "Human-readable description"
}
```

### Error Reference

#### 400 Bad Request

**`INVALID_REQUEST_FIELDS`**

* **Cause**: Missing or malformed required fields in the request body
* **Solution**: Verify all required parameters are present and correctly formatted

**`MIGRATION_REQUIRED`**

* **Cause**: A v2 signing endpoint was called for a v1 wallet without supplying `encryption_context`
* **Solution**: Include `encryption_context` on the first v2 call for that wallet. See the [migration guide](/server-wallets/core-api/v1-to-v2-migration)

#### 401 Unauthorized

**`INVALID_CREDENTIALS`**

* **Cause**: The `access_key` or `op_jwt` is invalid, or `iss`/`sub` in the `op_jwt` does not match the wallet's identity binding
* **Solution**: Verify `access_key` is the value returned at wallet creation. Ensure the JWT is signed by the same identity that created the wallet — `iss` and `sub` must be byte-identical

#### 403 Forbidden

**`MISSING_REQUIRED_HEADER`** (HTTP 403)

* **Cause**: The `x-magic-secret-key` header is missing
* **Solution**: Include `x-magic-secret-key: sk_live_XXXXXXXX` on every request

**`INVALID_API_KEY`** (HTTP 403)

* **Cause**: The secret key is invalid or does not match a known application
* **Solution**: Verify your secret key in the Magic Dashboard

#### 404 Not Found

**`NOT_FOUND`**

* **Cause**: The `wallet_id` does not exist or does not belong to your application
* **Solution**: Verify the wallet ID was created by your application

#### 429 Too Many Requests

**`RATE_LIMITED`**

* **Cause**: Exceeded the rate limit of 25 requests/second
* **Solution**: Back off and retry. Implement exponential backoff for bursts

#### 500 Internal Server Error

**`INTERNAL_ERROR`**

* **Cause**: An unexpected error occurred, including JWT validation failures inside the enclave (expired token, unknown `kid`, forbidden header parameter, binding mismatch)
* **Solution**: Check that your `op_jwt` is not expired, uses a supported issuer, and has `kid` in the header. If the issue persists, contact Magic support

#### 503 Service Unavailable

**`SERVICE_UNAVAILABLE`**

* **Cause**: The enclave pool is overloaded
* **Solution**: Retry with exponential backoff

### Best Practices

<Tip>
  * Implement exponential backoff for `429` and `503` responses
  * Generate `op_jwt` as close to the request as possible — tokens expire quickly
  * Never log `op_jwt` or `access_key` values
</Tip>