Errors and conventions

Errors

Every error has the same shape:

{
  "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.
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.

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:

{
  "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.

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.

Get started

MCP server

API reference

Endpoints

Errors and conventions

Errors

IDs

Timestamps

Run status

Download links

​Errors

​IDs

​Pagination

​Timestamps

​Run status

​Download links

Errors

IDs

Pagination

Timestamps

Run status

Download links