---
title: "API errors"
description: "The error codes of the API of a CIHub instance, with the HTTP status of each and what it means."
canonical_url: "https://cihub.io/docs/api/errors"
markdown_url: "https://cihub.io/docs/api/errors.md"
---

# API errors

An error of the API is an `application/problem+json` document (RFC 9457):

```json
{
  "type": "https://cihub.io/docs/api/errors#queue_not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "no queue of `main`",
  "code": "queue_not_found"
}
```

| Field    | Meaning                                                              |
| -------- | -------------------------------------------------------------------- |
| `type`   | The section of this page that explains `code`                        |
| `title`  | The reason phrase of the HTTP status                                 |
| `status` | The HTTP status of the answer                                        |
| `detail` | What went wrong with this request, for a person; its text can change |
| `code`   | The cause of the error, from the closed list below: decide on it     |

Each code has one HTTP status. A `429` also carries the header `Retry-After`: the seconds to wait before the next
request. The [OpenAPI document](/openapi/v1.json) lists, for each route, the codes that it can answer.

## 400 Bad Request

### `invalid_request`

The body, the path or the query of the request is not valid.

### `limit_out_of_range`

`limit` is from 1 to 100.

### `invalid_cursor`

`from` is not a `cursor` that this list gave.

### `unknown_priority`

The name of the priority is not `urgent`, `high`, `medium` or `low`.

### `device_code_pending`

The person has not approved or denied the code yet: ask again after `interval` seconds.

### `device_code_expired`

The device code is unknown, already used, or older than 15 minutes: start again.

## 401 Unauthorized

### `unauthorized`

No API token or session, or one that is unknown or expired.

## 403 Forbidden

### `scope_missing`

The token, or the role of the user of the session or their permission on the repository, lacks the scope of the route.

### `csrf_refused`

A request of a session that can change a state lacks the header `X-CSRF-Token`, or carries another token than the cookie `__Host-cihub_csrf`.

### `device_code_denied`

The person denied the code: the command line is not signed in.

## 404 Not Found

### `route_not_found`

No route has this path.

### `org_not_found`

No organization has this slug, or the token or the user does not belong to it.

### `repo_not_found`

The organization has no repository with this name.

### `queue_not_found`

The repository has no queue of this branch.

### `pr_not_found`

The PR was never submitted to a queue of the repository.

### `run_not_found`

The organization has no run with this identifier.

### `device_code_not_found`

No sign-in of the command line waits for this code: it is wrong, used, or older than 15 minutes.

## 409 Conflict

### `pr_already_queued`

The PR is already in a queue of the repository, and its item has not ended.

### `item_ended`

The item of the PR ended: `merged`, `failed` or `cancelled`.

### `item_not_in_test`

Only an item in `testing` or `pending_failure` can restart its tests.

## 429 Too Many Requests

### `rate_limited`

The token, the session or the client address made too many requests in the minute (600 for a token or a session, 120 for the sign-in of the command line): retry after `Retry-After` seconds.

### `too_many_streams`

The token or the person already keeps 8 streams open.

### `polling_too_fast`

The command line asked again sooner than `interval`: wait 5 seconds more each time.

## 500 Internal Server Error

### `internal`

The server failed; the logs of the instance say why.

## 503 Service Unavailable

### `sign_in_unavailable`

The instance has no public address or no sign-in client: nobody signs in to it.

### `scm_unavailable`

The SCM did not answer the check of the access of the person of the session: try again in a moment.