# Errors

The Limy API uses standard HTTP status codes and returns structured error responses.

## Error Response Format

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error."
  }
}
```

## HTTP Status Codes

| Code                        | Meaning               | When                                                       |
| --------------------------- | --------------------- | ---------------------------------------------------------- |
| `200 OK`                    | Success               | Request completed successfully                             |
| `400 Bad Request`           | Invalid parameters    | Missing required params, invalid format, bad filter values |
| `401 Unauthorized`          | Authentication failed | Missing or expired JWT token                               |
| `403 Forbidden`             | Access denied         | Valid token but insufficient role/permissions              |
| `404 Not Found`             | Resource not found    | Invalid account ID, competitor ID, topic ID, etc.          |
| `429 Too Many Requests`     | Rate limited          | Exceeded 600 requests/hour per API key                     |
| `500 Internal Server Error` | Server error          | Unexpected error — contact support if persistent           |

## Error Codes

| Code                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| `UNAUTHORIZED`        | Missing or invalid authentication token            |
| `FORBIDDEN`           | Authenticated but not authorized for this resource |
| `NOT_FOUND`           | The requested resource does not exist              |
| `VALIDATION_ERROR`    | Request parameters failed validation               |
| `RATE_LIMIT_EXCEEDED` | Too many requests — check `Retry-After` header     |
| `INTERNAL_ERROR`      | Unexpected server error                            |

## Common Mistakes

### Invalid date format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "startDate must be a valid ISO 8601 date (e.g., 2026-01-01)"
  }
}
```

### Missing required parameter

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "entity is required for this endpoint"
  }
}
```

### Expired token

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token has expired. Exchange your access key for a new JWT."
  }
}
```

## Handling Errors

```python
import requests

response = requests.get(url, headers=headers)

if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    time.sleep(retry_after)
    response = requests.get(url, headers=headers)
elif response.status_code == 401:
    # Re-exchange access key for new JWT
    jwt = refresh_token()
    headers['Authorization'] = f'Bearer {jwt}'
    response = requests.get(url, headers=headers)
elif response.status_code >= 400:
    error = response.json().get('error', {})
    raise Exception(f"API Error {error.get('code')}: {error.get('message')}")
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api-reference.limy.ai/getting-started/errors.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.