> For the complete documentation index, see [llms.txt](https://docs.corpdev.ai/corpdev.ai-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.corpdev.ai/corpdev.ai-docs/errors-pagination-and-retries.md).

# Errors, pagination and retries

Build clients around the response contract of each endpoint. The public API does not use one pagination or asynchronous-job format for every operation.

## Errors

Normal application errors use an object such as:

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Document not found"
  }
}
```

An error may include `details`. Rate-limit responses can instead contain a string `error`, plus fields such as `category`, `limiter` and `retryAfterSeconds`. Read the HTTP status and tolerate both shapes.

| Status | Client action                                                                         |
| ------ | ------------------------------------------------------------------------------------- |
| 400    | Correct the request shape, missing fields or invalid identifiers.                     |
| 401    | Check the credential, expiry and revocation state.                                    |
| 402    | Inspect the credit or usage restriction before retrying metered work.                 |
| 403    | Check key scope, role and workspace enablement.                                       |
| 404    | Check the identifier and access; do not assume it proves global absence.              |
| 409    | Resolve the reported conflict, such as a stale document version or active job.        |
| 422    | Correct unsupported filters or invalid referenced resources.                          |
| 429    | Respect `Retry-After` and the indicated retry delay.                                  |
| 5xx    | Retry cautiously with bounded backoff; inspect job state before repeating a mutation. |

## Pagination

`GET /documents` accepts `limit` and `cursor`, plus supported filters such as `folderId`, `status` and `docType`. The default limit is 50 and the maximum is 200. Continue until `nextCursor` is null, including after an empty filtered page. Use cursors returned by the server and guard against repeated cursors; an unresolved cursor can restart from the first page.

Company and people search use numbered `page` and `per_page` fields instead. Company search defaults to 25 results per page, people search to 10, with a maximum of 100. Other endpoints have their own pagination fields; do not reuse a document cursor in another route family.

## Rate limits and credits

Handle HTTP 429 and the response's retry information instead of assuming a universal fixed allowance. Throttling and usage credits are separate controls. Clients sharing a network can also share an IP-based throttle.

“Read” describes permission, not price. Research, semantic sourcing, contact reveal or analysis can be metered even when the operation uses read scope. Confirm the specific operation and available credit pool before a large batch.

## Asynchronous work

An accepted request is not a completed deliverable. Keep the returned job or document identifier and poll the supported status endpoint. Generation creation can return 202; submitting a prompt to an existing document can return 200, including a queued result.

Use bounded polling intervals, stop on terminal status and surface a useful failure message. A timeout in your client does not prove the server did not create a job.

## Safe writes

Document creation supports `Idempotency-Key`. It is not a blanket guarantee for every mutation. For version-sensitive replacement operations, provide the required `expectedVersion`; on a conflict, fetch the latest document and reconcile changes before retrying.

Record operation IDs and status without logging secrets or full confidential payloads. Test failure handling in a designated test workspace before enabling a recurring integration.