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

# Errors

> Understand the public API error envelope and what each error code means.

All public API errors return a consistent JSON envelope. The `doc_url` links to the section on this page for the returned code:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Not Found. The resource may not exist, this key may lack the required scope, or the key's creator may have lost access. Check the key's scopes in Replo Settings and the creator's project or workspace access; a workspace owner can grant access.",
    "doc_url": "https://docs.replo.app/api-reference/errors#not_found"
  }
}
```

Every response also includes a `Request-Id` header. Include it when contacting [support@replo.app](mailto:support@replo.app) about a failed request.

### invalid\_request

**Status: 400.** The request body or query parameters are malformed, or the `Replo-Api-Version` header is missing or unsupported. The `message` explains what failed validation; fix the request and retry.

When the request fails validation, `issues` lists each rejected field (`param`, a dotted path such as `name` or `variants.0.available`) and why, up to 10. `param` is `null` for a rule that covers the whole request.

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid input: name: Invalid input: expected string, received undefined",
    "doc_url": "https://docs.replo.app/api-reference/errors#invalid_request",
    "issues": [
      {
        "param": "name",
        "message": "Invalid input: expected string, received undefined"
      }
    ]
  }
}
```

### invalid\_credentials

**Status: 401.** The API token is missing or invalid. Send your public API key as a bearer token in the `Authorization` header. If the key was revoked, create a new one from your Replo Settings.

### forbidden

**Status: 403.** The request is authenticated but was rejected outright. Ask a workspace owner to perform the action or to grant the key's creator access. Note that a key missing a required scope does not get this response: scope and access failures surface as [not\_found](#not_found) so responses never confirm private resource IDs.

### not\_found

**Status: 404.** The resource doesn't exist, the key lacks a required scope, or the key's creator lost access. Replo returns the same status for all three cases, so API responses do not confirm private resource IDs. If a known resource returns 404, check the key's scopes in your Replo Settings and its creator's current project access.

### conflict

**Status: 409.** The resource is in a state that conflicts with the request, such as a message sent while the agent is still working on the previous one, or while the session has a pending interaction. Wait for the turn to finish or resolve the interaction, then retry.

### rate\_limit\_exceeded

**Status: 429.** Too many requests. Wait for the number of seconds in the `Retry-After` header before retrying.

### internal\_error

**Status: 500.** Something failed on Replo's side. Retry the request; if it keeps failing, contact [support@replo.app](mailto:support@replo.app) with the `Request-Id` header value.

### service\_unavailable

**Status: 503.** A temporary outage. Retry with exponential backoff. When the message says the work is still running (a slow `POST /v1/sites`), the request succeeded and its result appears shortly: list the resource instead of repeating the request.

### payload\_too\_large

HTTP 413. File content exceeds the 10 MiB decoded limit for synchronous Files uploads and Asset copies. Choose a smaller file.


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