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

# ErynoaGroup API error codes reference

> Complete list of ErynoaGroup API error codes with HTTP status, error code strings, causes, and recommended actions for handling each error.

When a request fails, ErynoaGroup returns a structured JSON error response alongside an appropriate HTTP status code. Use the `code` field to programmatically identify and handle specific error conditions.

## Error response format

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The 'name' field is required.",
    "status": 422,
    "request_id": "req_01HX9P3NXVQMJRFT8K2BWYC7E",
    "details": [
      {
        "field": "name",
        "message": "This field is required."
      }
    ]
  }
}
```

Always log the `request_id` — include it when contacting support to help diagnose issues quickly.

## Error codes

### Authentication errors (401, 403)

| Code                 | Status | Description                           | Action                                       |
| -------------------- | ------ | ------------------------------------- | -------------------------------------------- |
| `missing_api_key`    | 401    | No `Authorization` header present     | Add `Authorization: Bearer YOUR_KEY` header  |
| `invalid_api_key`    | 401    | Key does not exist or is malformed    | Check the key in your dashboard              |
| `api_key_revoked`    | 401    | Key was revoked                       | Generate a new key                           |
| `api_key_expired`    | 401    | Key has passed its expiry date        | Generate a new key                           |
| `insufficient_scope` | 403    | Key lacks required permissions        | Create a key with the appropriate scope      |
| `ip_not_allowed`     | 403    | Request IP not on the key's allowlist | Update the IP allowlist or use an allowed IP |

### Validation errors (400, 422)

| Code                     | Status | Description                            | Action                                                |
| ------------------------ | ------ | -------------------------------------- | ----------------------------------------------------- |
| `invalid_request`        | 400    | Request is malformed or unparseable    | Check request body format and Content-Type            |
| `validation_error`       | 422    | One or more fields failed validation   | Check the `details` array for field-specific messages |
| `invalid_parameter`      | 400    | A query parameter has an invalid value | Review the parameter documentation                    |
| `missing_required_field` | 422    | A required field is absent             | Add the missing field to the request body             |

### Resource errors (404, 409)

| Code                      | Status | Description                                     | Action                                                       |
| ------------------------- | ------ | ----------------------------------------------- | ------------------------------------------------------------ |
| `resource_not_found`      | 404    | The requested resource does not exist           | Verify the resource ID                                       |
| `resource_already_exists` | 409    | A resource with this identifier already exists  | Use a different identifier or retrieve the existing resource |
| `resource_conflict`       | 409    | Operation conflicts with current resource state | Check the resource's current status before retrying          |

### Rate limit errors (429)

| Code                  | Status | Description                             | Action                                                  |
| --------------------- | ------ | --------------------------------------- | ------------------------------------------------------- |
| `rate_limit_exceeded` | 429    | Too many requests in the current window | Wait for `Retry-After` seconds, then retry with backoff |

### Server errors (500, 502, 503)

| Code                  | Status | Description                    | Action                                                   |
| --------------------- | ------ | ------------------------------ | -------------------------------------------------------- |
| `internal_error`      | 500    | Unexpected server error        | Retry after a short delay; contact support if persistent |
| `service_unavailable` | 503    | API is temporarily unavailable | Check the status page; retry with exponential backoff    |

## Handling errors in code

```python theme={null}
import requests
import time

def make_api_request(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, headers=headers, timeout=30)

            if response.status_code == 429:
                retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
                time.sleep(retry_after)
                continue

            if response.status_code >= 500:
                time.sleep(2 ** attempt)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.Timeout:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)
            else:
                raise

    raise Exception(f"Request failed after {max_retries} attempts")
```