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

# Status Codes

> HTTP status codes returned by the Poelis API

The API uses standard HTTP status codes. Always check the status code before parsing the body.

## Success

| Code          | Meaning          | When used                                                       |
| ------------- | ---------------- | --------------------------------------------------------------- |
| `200 OK`      | Success          | GET (single or list), PATCH, and other successful reads/updates |
| `201 Created` | Resource created | POST when a new resource is created                             |

## Client Errors

| Code                       | Meaning           | When used                                                                                           |
| -------------------------- | ----------------- | --------------------------------------------------------------------------------------------------- |
| `400 Bad Request`          | Invalid request   | Malformed body, invalid query params, or nonsensical combination of parameters                      |
| `401 Unauthorized`         | Not authenticated | Missing or invalid REST API key (see [Authentication](/api-reference/authentication))               |
| `403 Forbidden`            | No permission     | Valid REST API key but no access to this resource (e.g. other org)                                  |
| `404 Not Found`            | Resource missing  | Resource does not exist or is not visible to your organization                                      |
| `422 Unprocessable Entity` | Validation failed | Body/params valid in shape but fail validation (e.g. required field missing, format error)          |
| `429 Too Many Requests`    | Rate limited      | Too many requests; see [Rate Limiting](/guides/rate-limiting). Use `Retry-After` header to back off |

## Server Errors

| Code                        | Meaning          | When used                                                                        |
| --------------------------- | ---------------- | -------------------------------------------------------------------------------- |
| `500 Internal Server Error` | Server error     | Unexpected server failure; retry with backoff and contact support if it persists |
| `503 Service Unavailable`   | Temporary outage | Service temporarily unavailable; retry later                                     |

## Example Error Bodies

### 401 Unauthorized

```json theme={null}
{
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}
```

### 404 Not Found

```json theme={null}
{
  "error": "not_found",
  "message": "Resource not found"
}
```

### 422 Validation Error

```json theme={null}
{
  "error": "validation_error",
  "message": "Invalid data format",
  "details": {
    "field": "name",
    "reason": "Name must be at least 1 character"
  }
}
```

### 429 Rate Limit

**Body (JSON):**

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}
```

**Headers:** `Retry-After` (seconds, e.g. `"60"`), `X-RateLimit-Limit`, `X-RateLimit-Remaining` (`"0"` when exceeded), `X-RateLimit-Reset` (Unix timestamp in seconds, as string). See [Rate Limiting](/guides/rate-limiting) and [Error Handling](/guides/error-handling).