# Error codes

> Source: https://pixelsystems.com/docs/api/error-codes


Learn about the HTTP status codes and error responses returned by the API.

The API uses conventional [HTTP status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status): `2xx` means the request succeeded, `4xx` means the problem is with the request, and `5xx` means something failed on Pixel's side (rare). Whether and how to retry depends on the code; the table below covers each one.

## Error response format

Error responses use the [`ApiError`](https://pixelsystems.com/docs/api/resources#apierror) schema, a JSON object with these fields:

- `code`: the machine-readable error code. The table below lists every value.
- `message`: a human-readable explanation of what went wrong.
- `details`: optional; present when the error can point at what in the request was wrong. Its `issues` list one entry per problem, each with a dotted `path` (empty for the request as a whole) and, where the validator gives them, a `message` and its `code`. See [`ApiErrorDetails`](https://pixelsystems.com/docs/api/resources#apierrordetails).
- `retryAfter`: optional; the number of seconds to wait before retrying. Set for `rate_limited` and `service_unavailable`.

```json
{
  "code": "invalid_request",
  "message": "applicationId must be a valid UUID.",
  "details": {
    "issues": [
      {
        "path": "applicationId",
        "message": "Invalid uuid",
        "code": "invalid_format"
      }
    ]
  }
}
```

## Error codes

| Error code | HTTP status | Meaning |
| --- | --- | --- |
| `invalid_request` | `400` | The request is malformed: a missing or invalid parameter, or a body that is not the expected [`multipart/form-data`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/POST). `details.issues` names the offending fields when available. Fix the request before retrying. |
| `unsupported_format` | `400` | The uploaded file is not a type the application's [pipeline](https://pixelsystems.com/docs/concepts#pipeline) accepts. Each application's pipeline accepts one kind of file: a JPEG, PNG or [HEIC/HEIF](https://en.wikipedia.org/wiki/High_Efficiency_Image_File_Format) image, or a PDF. The error's message lists the types this application accepts, and names the file when a request carries several. |
| `unauthorized` | `401` | The API key is missing or invalid. Send it as [`Authorization: Bearer <api_key>`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Authorization); see [Authentication](https://pixelsystems.com/docs/api/authentication). |
| `forbidden` | `403` | The API key is valid, but API access is not enabled for its organization. Rotating the key does not help; [contact us](https://pixelsystems.com/contact) to enable it. See [Authentication](https://pixelsystems.com/docs/api/authentication). |
| `not_found` | `404` | The requested resource does not exist or is not visible to your application, for example a `jobId` from another application. |
| `file_too_large` | `413` | The file exceeds its upload limit: 25 MB for an image, 2 MB for a PDF. When a request carries several files, the error names the first one over its limit. |
| `unprocessable` | `422` | The file is a valid upload but cannot be analysed. Submitting the same file again returns the same error. |
| `rate_limited` | `429` | Too many requests. Wait `retryAfter` seconds before retrying; see [rate limits](https://pixelsystems.com/docs/api/rate-limits) for the limits and retry guidance. |
| `internal_error` | `500` | Something failed on Pixel's side. These are rare; retry a submission only with its original [`Idempotency-Key`](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/), so the retry returns the existing job instead of creating a duplicate. [Contact us](https://pixelsystems.com/contact) if it persists. |
| `service_unavailable` | `503` | The service is temporarily overloaded. Wait `retryAfter` seconds and retry with backoff. |