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:

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