All error responses are JSON with the shape below:

```json title="Error Response"
{
  "message": "Input validation failed",
  "code": "BAD_REQUEST",
  "issues": [
    {
      "path": ["name"],
      "message": "Required"
    }
  ]
}
```

## Common Causes [#common-causes]

* Missing required fields
* Invalid IDs or workspace access
* Rate limits exceeded
* Jobs not ready yet (poll later)

## Error Codes [#error-codes]

* `BAD_REQUEST` - Invalid input or failed validation
* `UNAUTHORIZED` - Missing or invalid API key
* `FORBIDDEN` - Access denied for this workspace
* `NOT_FOUND` - Resource does not exist
* `TOO_MANY_REQUESTS` - Rate limit exceeded
* `INTERNAL_SERVER_ERROR` - Unexpected failure

## Tips [#tips]

* Always check `res.ok` before reading JSON.
* For validation errors, inspect `issues` to find the exact field.
* For auth uncertainty, call `GET /auth/validate` with the same Bearer key.
* For route 404s, fetch `/api/openapi.json` and avoid guessed endpoints.