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

# Errors

> Error codes, response format, and troubleshooting.

## Error response format

All errors follow a consistent JSON structure:

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

## HTTP status codes

| Code  | Meaning                                      |
| ----- | -------------------------------------------- |
| `200` | Success                                      |
| `201` | Created                                      |
| `202` | Accepted (async job queued)                  |
| `204` | No Content (resource deleted)                |
| `400` | Bad Request — invalid parameters             |
| `401` | Unauthorized — missing or invalid API key    |
| `402` | Payment Required — insufficient credits      |
| `403` | Forbidden — valid key but insufficient scope |
| `404` | Not Found — resource does not exist          |
| `409` | Conflict — duplicate request (idempotency)   |
| `422` | Unprocessable Entity — validation error      |
| `429` | Too Many Requests — rate limited             |
| `500` | Internal Server Error                        |

## Common error codes

| Code                   | Description                                               |
| ---------------------- | --------------------------------------------------------- |
| `UNAUTHORIZED`         | API key is missing or invalid                             |
| `FORBIDDEN`            | Key lacks the required scope                              |
| `INSUFFICIENT_CREDITS` | Wallet balance too low                                    |
| `RATE_LIMITED`         | Too many requests                                         |
| `VALIDATION_ERROR`     | Request body failed validation                            |
| `RESOURCE_NOT_FOUND`   | The requested resource does not exist                     |
| `IDEMPOTENCY_CONFLICT` | A request with this idempotency key was already processed |
| `MODEL_NOT_AVAILABLE`  | The requested AI model is not available on your plan      |
| `JOB_FAILED`           | An async job encountered an error                         |

## Idempotency

For POST requests, include an `X-Idempotency-Key` header to prevent duplicate operations:

```bash theme={null}
curl -X POST https://api.smartlyq.com/v1/articles/generate \
  -H "Authorization: Bearer sqk_live_xxxxxxxxxxxx" \
  -H "X-Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{ "topic": "My Article", "language": "en" }'
```

Idempotency keys expire after **24 hours**.