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

# Errors

> Understand API errors, status codes, and how to troubleshoot failed requests.

The 1eye API uses standard HTTP status codes and a consistent JSON error format.

## Error response format

All API errors return an `error` object.

```text theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown query parameter: emial.",
    "param": "emial",
    "request_id": "req_359051753366339585"
  }
}
```

The error object can include:

| Field        | Description                             |
| :----------- | :-------------------------------------- |
| `code`       | Stable, machine-readable error code     |
| `message`    | Human-readable description of the error |
| `param`      | The invalid parameter, when applicable  |
| `request_id` | Unique ID for the API request           |

## HTTP status codes

| HTTP Status                 | Error Code             | Description                                                    |
| :-------------------------- | :--------------------- | :------------------------------------------------------------- |
| `400 Bad Request`           | `invalid_request`      | The request is malformed                                       |
| `400 Bad Request`           | `invalid_parameter`    | A query parameter or parameter value is invalid                |
| `400 Bad Request`           | `invalid_cursor`       | The pagination cursor is invalid or does not match the request |
| `401 Unauthorized`          | `authentication_error` | The API key is missing, invalid, or revoked                    |
| `404 Not Found`             | `not_found`            | The requested resource is unavailable to the workspace         |
| `429 Too Many Requests`     | `rate_limit_exceeded`  | The workspace has exceeded an API rate limit                   |
| `500 Internal Server Error` | `internal_error`       | An unexpected server error occurred                            |
| `503 Service Unavailable`   | `service_unavailable`  | The API is temporarily unavailable                             |

## Invalid request

Malformed requests return:

```text theme={null}
400 Bad Request
```

with:

```text theme={null}
invalid_request
```

## Invalid parameter

Unknown query parameters, invalid values, unsupported sort fields, and other parameter validation errors return:

```text theme={null}
400 Bad Request
```

Example:

```text theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "Unknown query parameter: emial.",
    "param": "emial",
    "request_id": "req_359051753366339585"
  }
}
```

The 1eye API does not silently ignore unknown query parameters.

## Invalid cursor

Malformed, modified, or mismatched pagination cursors return:

```text theme={null}
400 Bad Request
```

with:

```text theme={null}
invalid_cursor
```

Cursors must be used with the same endpoint, filters, and sorting that were used to generate them.

## Authentication errors

A missing, invalid, or revoked API key returns:

```text theme={null}
401 Unauthorized
```

Example:

```text theme={null}
{
  "error": {
    "code": "authentication_error",
    "message": "Invalid or missing API key.",
    "request_id": "req_359051753366339585"
  }
}
```

## Resource not found

If a requested resource does not exist or belongs to another workspace, the API returns:

```text theme={null}
404 Not Found
```

with:

```text theme={null}
not_found
```

The API does not reveal whether a resource exists in another workspace.

## Rate limit errors

When a workspace exceeds an API rate limit, the API returns:

```text theme={null}
429 Too Many Requests
```

with:

```text theme={null}
rate_limit_exceeded
```

Example:

```text theme={null}
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Workspace API rate limit exceeded. Please retry later.",
    "request_id": "req_359051753366339585"
  }
}
```

Rate-limited responses may include:

```text theme={null}
Retry-After: 12
```

When present, `Retry-After` indicates how long to wait before retrying the request.

## Server errors

Unexpected server errors return:

```text theme={null}
500 Internal Server Error
```

with:

```text theme={null}
internal_error
```

If the API is temporarily unavailable, it returns:

```text theme={null}
503 Service Unavailable
```

with:

```text theme={null}
service_unavailable
```

## Request IDs

Every API request receives a unique request ID.

It is returned in the response header:

```text theme={null}
X-Request-Id: req_359051753366339585
```

Error responses also include the same value as `error.request_id`.

Use the request ID when reviewing API Logs or contacting 1eye support about a failed request.