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

# Errors

> Status codes and error response shape.

## Error response shape

Non-2xx responses return JSON:

```json theme={null}
{
  "error": "machine_readable_code",
  "message": "Human-readable description.",
  "requestId": "req_abc123..."
}
```

* `error` is stable — code your branching logic against this.
* `message` is for humans; we may rephrase it without notice.
* `requestId` is what you mention to support when something is broken.

## Status codes

| Code                        | When                                                 |
| --------------------------- | ---------------------------------------------------- |
| `200 OK`                    | Successful read                                      |
| `201 Created`               | Resource created                                     |
| `202 Accepted`              | Async operation queued (e.g. build dispatch)         |
| `204 No Content`            | Successful write with no body                        |
| `400 Bad Request`           | Invalid input                                        |
| `401 Unauthorized`          | Missing or invalid token                             |
| `403 Forbidden`             | Token lacks permission for this action               |
| `404 Not Found`             | Resource doesn't exist or you can't see it           |
| `429 Too Many Requests`     | Rate-limited; see `Retry-After` header               |
| `500 Internal Server Error` | Bug on our side — include `requestId` when reporting |

## Common error codes

| Code                   | Description                                 |
| ---------------------- | ------------------------------------------- |
| `invalid_token`        | Token is malformed, revoked, or expired.    |
| `insufficient_scope`   | Token doesn't have the required permission. |
| `validation_failed`    | Input failed schema validation.             |
| `engine_not_found`     | Requested `ueVersion` is not supported.     |
| `repo_not_accessible`  | GitHub App lost access to the repo.         |
| `perforce_auth_failed` | Perforce credentials rejected.              |

## Rate limiting

When rate-limited:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

Wait `Retry-After` seconds before the next request.