> For the complete documentation index, see [llms.txt](https://manual.personr.co/api-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.personr.co/api-documentation/getting-started/errors-and-rate-limits.md).

# Errors and rate limits

How errors are returned, the error messages you can expect, and how fast you can call the API.

## Check the body, not just the status code

Most errors come back as HTTP `400` or `401`. Some endpoints return HTTP `200` with an error in the body, so always check the body before treating a response as a success:

* `"status": "error"` at the top level
* an `error` key, either at the top level or inside `response`
* a `response` that is a message rather than an object (for example `"No entity found"`)

We're moving every endpoint to the standard shapes below. When an endpoint changes, it will be listed in the [Changelog](https://manual.personr.co/api-documentation/getting-started/changelog.md).

## Error shapes

| HTTP  | Body                                                                                                                              | When                                                                                                                                     |
| ----- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `{"statusCode": 400, "message": "Error: incorrect applicantId provided"}`                                                         | Bad or unknown ID, bad `docType`, bad `flowName` (database verification), bad `modelName`                                                |
| `400` | `{"statusCode": 400, "reason": "INVALID_LOGIN_CREDENTIALS", "message": "We didn't find an account with those login credentials"}` | Wrong email or password when generating a token                                                                                          |
| `401` | `{"error_class": "Unauthorized", "message": null, "translation": "Invalid or expired token: ..."}`                                | Missing, wrong or expired Bearer token                                                                                                   |
| `200` | `{"status": "error", "error": "flow_not_found", "message": "...", "flowName": "...", "workspace": "..."}`                         | No active flow with that name in the token's workspace                                                                                   |
| `200` | `{"status": "error", "error": "applicant_not_found", "message": "..."}`                                                           | Document endpoints: the applicant ID is empty or belongs to another workspace. On `api-document-upload`, also when the ID doesn't exist. |
| `200` | `{"status": "error", "error": "entity_not_found", "message": "..."}`                                                              | Entity document uploads: the entity ID is empty, doesn't exist or belongs to another workspace                                           |
| `200` | `{"status": "success", "response": {"error": "invalid_return_url", "message": "..."}}`                                            | `returnUrl` isn't a full URL. No link is created.                                                                                        |
| `200` | `{"status": "error", "response": "<message>"}`                                                                                    | Lookups, workspace switching, `api-retrieve-ownership` with `format=standard`                                                            |
| `200` | `{"response": "<message>"}`                                                                                                       | `api-retrieve-ownership` (without `format`), `api-retrieve-ubo`                                                                          |
| `200` | `{"error": "Unauthorised. User does not have permissions."}`                                                                      | Webhook configuration by a user who isn't an administrator                                                                               |

## Error messages by endpoint

| Endpoint                                                            | Message                                                                | What to do                                                                                                                                  |
| ------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `api-token-generate`, `api-basic-auth`                              | `INVALID_LOGIN_CREDENTIALS`                                            | Check the email and password of the API user                                                                                                |
| Any endpoint taking `applicantId`                                   | `Error: incorrect applicantId provided` / `Error: invalid applicantId` | The ID doesn't exist, or belongs to another workspace. The document endpoints below use `applicant_not_found` / `entity_not_found` instead. |
| `api-document-upload`                                               | `applicant_not_found`                                                  | The ID is empty, doesn't exist or belongs to another workspace. Nothing is uploaded. Use the API key of the applicant's workspace.          |
| `api-document-download`, `api-document-download-information`        | `applicant_not_found`                                                  | The ID is empty or belongs to another workspace. Use the API key of the applicant's workspace. An ID that doesn't exist returns `400`.      |
| `api-entity-document-upload`, `api-entity-document-upload-encoded`  | `entity_not_found`                                                     | The ID is empty, doesn't exist or belongs to another workspace. Nothing is uploaded. Use the API key of the entity's workspace.             |
| `api-applicant-create`, `api-entity-create`                         | `flow_not_found`                                                       | Check `flowName`, or use the right workspace's API key                                                                                      |
| `api-database-verification`, `api-entity-database-verification`     | `Error: incorrect flowName provided`                                   | Check `flowName`                                                                                                                            |
| `api-document-upload`                                               | `Error: Cannot read docSets - invalid docType provided.`               | Use a value from Supported Documents and Types                                                                                              |
| `api-verificationlink-create`, `api-entity-verificationlink-create` | `invalid_return_url`                                                   | Send `https://...` or your app's scheme (`myapp://...`)                                                                                     |
| `api-entity-document-upload-encoded`                                | Rejected when `docFile` is over 1 MiB                                  | Use `api-entity-document-upload` for larger files (up to 6 MB)                                                                              |
| `api-retrieve-ownership`, `api-retrieve-ubo`                        | `No entity found` / `No ownership found`                               | Wrong ID, or ownership hasn't finished building. Wait for `entity.ownership_ready`.                                                         |
| `api-lookup-create`                                                 | `Set aml or documentCheck to true` / `Invalid documentType`            | Fix the request                                                                                                                             |
| `api-lookup-retrieve`                                               | `No lookup found`                                                      | Check the lookup ID                                                                                                                         |
| `api-change-workspace`                                              | `Workspace not found, or this is a workspace API key...`               | Workspace API keys can't switch workspace                                                                                                   |
| `api-deepfake-detection`                                            | `Error: incorrect modelName provided`                                  | Check `modelName`                                                                                                                           |

{% hint style="warning" %}
`api-aml-results` returns `{"aml": []}` both when there are no matches and when the `applicantId` belongs to another workspace. Check the ID with `api-applicant-status` or `api-entity-status` first if you expected matches.
{% endhint %}

## Server errors

* `5xx` responses and timeouts are rare. They're safe to retry for read endpoints (`*-status`, `*-retrieve-*`, `api-aml-results`).
* For create endpoints, check whether the record exists before retrying, so you don't create a duplicate. Search for it by your `sourceKey` or `externalUserId`.

## Rate limits

We don't currently enforce rate limits or return `429` responses. To keep your integration reliable:

* Use webhooks instead of polling status endpoints. If you must poll, space your checks out rather than polling in a tight loop.
* Before a large bulk run, tell us at <help@personr.co>.
* Retry `5xx` errors with exponential backoff (for example 1s, 2s, 4s, 8s).

If we introduce enforced limits, we'll announce them in the [Changelog](https://manual.personr.co/api-documentation/getting-started/changelog.md) beforehand. Requests over the limit will then return `429` with a `Retry-After` header.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://manual.personr.co/api-documentation/getting-started/errors-and-rate-limits.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
