---
updatedAt: 2026-02-08T13:32:32.000Z
agentTools:
  projectIndex: https://neutronpay.readme.io/llms.txt
---

# Error Handling

The Neutron API uses standard HTTP status codes and returns consistent JSON error responses to help you quickly identify and resolve issues.

## HTTP Status Codes

| Code    | Category        | Description                                                                                  |
| ------- | --------------- | -------------------------------------------------------------------------------------------- |
| **200** | ✅ Success       | Request completed successfully                                                               |
| **400** | ❌ Bad Request   | The request was malformed or missing required fields                                         |
| **401** | 🔒 Unauthorized | Authentication failed — invalid API key, signature, or expired token                         |
| **403** | 🚫 Forbidden    | Valid credentials but insufficient permissions (e.g., accessing another account's resources) |
| **404** | ❓ Not Found     | The requested resource doesn't exist (transaction, webhook, account, etc.)                   |
| **429** | ⏳ Rate Limited  | Too many requests — see [Rate Limiting](/reference/rate-limits)                              |
| **500** | 💥 Server Error | Something went wrong on our end — retry with exponential backoff                             |

## Error Response Format

All error responses return JSON with an `error` field, and optionally a `message` field with more detail:

```json
{
  "error": "unauthorized",
  "message": "invalid token or token expired"
}
```

Some endpoints return a simpler format:

```json
{
  "error": "invalid api signature"
}
```

## Common Errors by Category

### Authentication Errors

| Error                            | HTTP Code | Cause                                                         | Solution                                                                                                                                                                       |
| -------------------------------- | --------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `invalid API key or signature`   | 401       | Missing or incorrect `X-Api-Key` or `X-Api-Signature` headers | Verify your API key and regenerate the HMAC-SHA256 signature — see [Signature Generation](/reference/signature-generation)                                                     |
| `invalid api signature`          | 401       | The signature doesn't match the expected value                | Ensure you're signing the string `{apiKey}&payload={payload}` with your API secret using HMAC-SHA256                                                                           |
| `invalid token or token expired` | 401       | The JWT access token has expired or is malformed              | Request a new token via [POST /api/v2/authentication/token-signature](/reference/authenticatewithtokensignature). Tokens have a limited lifespan — check the `expiredAt` field |

### Account & Wallet Errors

| Error                                         | HTTP Code | Cause                                               | Solution                                                                    |
| --------------------------------------------- | --------- | --------------------------------------------------- | --------------------------------------------------------------------------- |
| `failed to get account`                       | 400       | Invalid account ID format                           | Verify the account ID (format: `ne01-xxxx...`)                              |
| `you are not authorized to view this account` | 401       | Trying to access an account you don't own           | You can only access your own account or subaccounts where you're the parent |
| `Permission denied`                           | 403       | Subaccount accessing parent resources or vice versa | Ensure the token matches the account being accessed                         |

### Transaction Errors

| Error          | HTTP Code | Cause                           | Solution                                                                                      |
| -------------- | --------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
| `unauthorized` | 401       | Missing or invalid Bearer token | Include a valid JWT in the `Authorization: Bearer {token}` header                             |
| `not found`    | 404       | Transaction ID doesn't exist    | Verify the transaction ID from the create response                                            |
| `bad request`  | 400       | Invalid transaction parameters  | Check required fields: `sourceReq` and `destReq` with valid `ccy`, `method`, and `reqDetails` |

### Webhook Errors

| Error          | HTTP Code | Cause                             | Solution                                                                                |
| -------------- | --------- | --------------------------------- | --------------------------------------------------------------------------------------- |
| `unauthorized` | 401       | Missing or invalid authentication | Include a valid Bearer token                                                            |
| `not found`    | 404       | Webhook ID doesn't exist          | List your webhooks via [GET /api/v2/webhook](/reference/listwebhooks) to find valid IDs |

## Error Handling Best Practices

1. **Always check the HTTP status code first** — it tells you the error category
2. **Parse the JSON `error` and `message` fields** for specifics
3. **Implement token refresh logic** — tokens expire, so catch 401s and re-authenticate automatically
4. **Use idempotent retries for 5xx errors** — server errors are usually transient; retry with exponential backoff
5. **Don't retry 4xx errors without fixing the request** — these indicate a problem with your input
6. **Log error responses** — include the full response body in your logs for debugging
7. **Set up [webhooks](/reference/createwebhook)** to track transaction failures asynchronously instead of polling