## Error schema

UseAgents errors use standard HTTP status codes plus a machine-readable error code. Typical error responses look like this:

```json
{
  "error": {
    "status": 422,
    "code": "validation_error",
    "message": "We found an error with one or more fields in the request."
  }
}
```

## Error codes

### `validation_error`
- **Status:** 422
- **Message:** We found an error with one or more fields in the request.
- **Suggested action:** Read the validation details, then fix the invalid field or request shape.

### `method_not_allowed`
- **Status:** 405
- **Message:** Method is not allowed for the requested path.
- **Suggested action:** Use the correct HTTP method for the endpoint.

### `not_found`
- **Status:** 404
- **Message:** The requested endpoint does not exist or the requested resource was not found.
- **Suggested action:** Check the request path and confirm the resource exists.

### `rate_limit_exceeded`
- **Status:** 429
- **Message:** You have exceeded your request limit. Please try again later.
- **Suggested action:** Back off, reduce request frequency, and retry after the window resets.

### `missing_api_key`
- **Status:** 401
- **Message:** Missing API key in the authorization header.
- **Suggested action:** Include `Authorization: Bearer YOUR_API_KEY` on protected requests.

### `invalid_api_key`
- **Status:** 403
- **Message:** API key is invalid.
- **Suggested action:** Verify the key is correct or generate a new one in the [Dashboard](/content/dashboard/index.html).

### `internal_server_error`
- **Status:** 500
- **Message:** An unexpected error occurred.
- **Suggested action:** Retry later and check the [Status page](/content/status/index.html) if the issue persists.

## Troubleshooting workflow
1. Check the HTTP status code.
2. Read the `error.code` and `message`.
3. Fix the request shape, authentication, or request rate.
4. Retry the request.
5. If the issue is a `5xx`, check [Status](/content/status/index.html) before retrying repeatedly.