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

# Errors and conventions

> How the Revilico REST API formats errors, and its conventions for ID prefixes, cursor pagination, UTC timestamps, run statuses and download links.

## Errors

Every error has the same shape:

```json theme={null}
{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid parameters for RevRedox.",
    "details": {
      "issues": [
        { "path": "parameters.charge", "message": "Too big: expected number to be <=10" }
      ]
    }
  }
}
```

* `code` is stable: branch on it, not on `message`. Codes are never renamed or removed within `/v1`.
* `message` explains the problem for people and may change.
* `details` is there when there is more to say. Validation errors list each problem in `details.issues`, with the `path` of the field.

| Status | `error.code` | Meaning |
| - | - | - |
| 400 | `VALIDATION_FAILED` | The body or query string is malformed. See `details.issues`. |
| 400 | `INVALID_ID` | An ID in the path is malformed or of the wrong kind, such as a file ID where a run ID belongs. |
| 401 | `MISSING_CREDENTIALS`, `INVALID_CREDENTIALS`, `CREDENTIALS_EXPIRED`, `CREDENTIALS_REVOKED`, `WRONG_ENVIRONMENT` | The API key is missing or not valid. See [Authentication](https://docs.revilico.bio/developers/authentication.md#authentication-errors). |
| 402 | `INSUFFICIENT_CREDITS` | Your organization doesn't have enough credits to start the run. |
| 403 | `INSUFFICIENT_SCOPE` | The key lacks the scope the endpoint needs. |
| 403 | `ENGINE_NOT_ENABLED` | Your plan doesn't include this engine. |
| 403 | `API_ACCESS_NOT_ENABLED`, `ACCOUNT_INACTIVE` | API access is off for your organization, or the account is inactive. |
| 403 | `FORBIDDEN` | You can see this but not change it, such as a project where you are a viewer. |
| 404 | `NOT_FOUND` | It doesn't exist, or you can't see it. |
| 409 | `RUN_NOT_COMPLETE` | Results and outputs exist only once a run has succeeded. |
| 409 | `CONFLICT` | The request conflicts with the current state, such as cancelling a run that has finished. |
| 413 | `PAYLOAD_TOO_LARGE` | The result is too large to return as JSON. Download the file instead. |
| 422 | `INVALID_PARAMETERS` | The parameters or input files don't match the engine. See `details.issues`. |
| 422 | `INPUT_LIMIT_EXCEEDED` | An input is over the engine's limits, such as too many molecules. |
| 500 | `INTERNAL_ERROR` | Something went wrong on our side. Try again. |
| 502 | `ENGINE_SUBMIT_FAILED` | The engine service rejected or failed the request. |
| 503 | `SERVICE_UNAVAILABLE` | The service is temporarily unavailable. Try again shortly. |

> [!TIP]
>
> Before you start a run, `POST /v1/engines/{engine}/validate` catches `INVALID_PARAMETERS` without running anything or spending credits.

## IDs

IDs start with a prefix that says what they are: `run_`, `file_`, `proj_` and `key_`. Treat them as opaque strings.

## Pagination

List endpoints return one page at a time:

```json theme={null}
{
  "data": [ … ],
  "nextCursor": "eyJvZmZzZXQiOjEwMH0"
}
```

To get the next page, send the same request with `cursor` set to `nextCursor`. `nextCursor` is `null` on the last page. Set the page size with `limit`; each endpoint documents its default and maximum.

```bash theme={null}
curl "https://public-api.revilico.bio/v1/runs?limit=50&cursor=eyJvZmZzZXQiOjEwMH0" \
  -H "Authorization: Bearer $REVILICO_API_KEY"
```

## Timestamps

Timestamps are ISO 8601 date-times in UTC, such as `2026-10-26T14:03:12.000Z`.

## Run status

| `status` | Meaning |
| - | - |
| `queued` | Accepted and waiting for the engine to pick it up |
| `running` | The engine is working on it |
| `succeeded` | Finished; results and outputs are ready |
| `failed` | Stopped with an error; see `error.message` |
| `cancelled` | Stopped before finishing; `statusReason` says why: `user`, `insufficient_credits` or `budget_exceeded` |

`succeeded`, `failed` and `cancelled` are final.

## Download links

Download URLs for files and outputs are pre-signed and expire after 15 minutes. Fetch them without the `Authorization` header, and request a new one when it expires.


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