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

# Errors

> One error shape on every route, and what to do about each code.

Every error is `application/json` with one object, `error`:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "not_found",
    "message": "No such task version, or none this key can use.",
    "param": null,
    "errors": [],
    "doc_url": "…/errors/not_found",
    "request_id": "req_00d1ghp0tcar9fcc8pa11p3jp4jt7wnb71eh"
  }
}
```

| Field | What it is |
| - | - |
| `code` | What went wrong. **Branch on this.** It is stable, and new codes may be added |
| `type` | `invalid_request_error` (fix the request) or `api_error` (our side). New types may be added |
| `message` | For a person. It may change, so don't parse it |
| `param` | The field at fault, when there is one |
| `errors` | On a `400`: every invalid field, each with its `param` and a `message` |
| `doc_url` | This page, at the code |
| `request_id` | Quote it when you contact us |

Every response, error or not, carries a `Request-Id` header with the same ID.

A message never repeats a value you sent: a `400` names the field, not its content.

## Codes

### invalid\_request

`400`. The body doesn't match the schema, for example a missing `answer` or a field we don't know. Fix the request;
`errors` lists every field at fault. Retrying it unchanged gets the same `400`.

### unauthenticated

`401`. The key is missing, unknown or revoked. See [Authentication](https://docs.aicmelabs.com/authentication.md).

### forbidden

`403`. The key is valid, but it isn't a key that can use this route. A task is never `403`: a task you can't see is
`404`.

### not\_found

`404`. The resource doesn't exist, **or your lab can't see it**. The response is the same either way. That covers a
task your lab isn't granted, a version that isn't published, and another lab's reward. An ID that isn't well formed
is `404` too, never `400`: IDs are opaque.

### version\_retired

`410`. The task version, or the judge version, is past its sunset. Move to the current version. Once a newer
version is published, downloading the older one's package returns `Deprecation` and `Sunset` headers
([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745), [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)), so you
can move in time.

### request\_too\_large

`413`. The request body is over 512 KB. Nothing was created. The package's verifier never sends one; see
[Limits](https://docs.aicmelabs.com/limits.md).

### rate\_limited

`429`. Your lab already has 2,000 rewards pending, its limit. Nothing was created. The response has a `Retry-After`
header, in seconds: post again after it, as your pending rewards finish. Posting an answer whose reward is pending
or scored still returns that reward; an answer whose reward failed is scored again, as a new pending reward. See
[Limits](https://docs.aicmelabs.com/limits.md).

### internal

`500`. Our fault. The body says nothing more than that, and gives the `request_id`: send it to us. A package whose
bytes fail our check is never served: you get this instead.

### service\_unavailable

`503`. Something we depend on is down. The response has a `Retry-After` header, in seconds.

The request may or may not have taken effect. Retrying is safe: posting the same answer again returns the same reward
rather than scoring it twice. Wait for `Retry-After`, and back off exponentially with jitter, up to 60 seconds, if it
repeats.

## Retrying

| Status | Retry? |
| - | - |
| `400`, `401`, `403`, `404`, `410`, `413` | No. Fix the request, the key or the version |
| `429` | Yes, after `Retry-After`, once some of your pending rewards finish |
| `500` | Once or twice, then send us the `request_id` |
| `503` | Yes, after `Retry-After`, with exponential backoff and jitter |

A reward with `status: failed` isn't an error response. See [A failed reward](https://docs.aicmelabs.com/rewards.md#a-failed-reward).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.