# Errors

Every error response has the same JSON shape:

```json
{
  "code": "invalid_request",
  "message": "The `name` field is required.",
  "request_id": "req_01H8Z9XJ7M3K4P5Q6R7S8T9V0W"
}
```

Include `request_id` whenever you contact support — it lets us trace the
specific call in our logs.

## Status codes

| Status | Meaning                                                         |
| ------ | --------------------------------------------------------------- |
| `200`  | OK. The request succeeded.                                      |
| `201`  | Created. A new resource was created.                            |
| `204`  | No Content. The request succeeded and there is no response body.|
| `400`  | Bad Request. The request was malformed. See `code`.             |
| `401`  | Unauthorized. The API key is missing or invalid.                |
| `403`  | Forbidden. The API key lacks the required scope.                |
| `404`  | Not Found. The requested resource does not exist.               |
| `409`  | Conflict. The request collides with current state.              |
| `429`  | Too Many Requests. You hit a rate limit — back off and retry.   |
| `500`  | Internal Server Error. Something went wrong on our side.        |

## Common error codes

| `code`               | When you'll see it                                                |
| -------------------- | ------------------------------------------------------------------ |
| `invalid_request`    | A field is missing, wrong type, or out of range.                  |
| `authentication`     | The API key is invalid, revoked, or not provided.                 |
| `permission_denied`  | The key is valid but lacks the required scope.                    |
| `not_found`          | The resource ID does not exist on this account.                   |
| `rate_limited`       | Too many requests in a short window.                              |
| `internal`           | An unexpected server-side failure.                                |