Reference · v1
Errors, limits and recovery
REST errors use a stable JSON envelope. Treat the HTTP status and error code as machine-readable information; display the message when useful.
{
"error": {
"code": "invalid_token",
"message": "A valid OAuth grant is required."
}
}| Status | Meaning | Next action |
|---|---|---|
| 400 | Invalid path, fields, query, headers or request shape. | Correct the request; do not blindly retry. |
| 401 | Missing, expired or invalid Bearer authorization. | Refresh once when appropriate, or start a new user authorization. |
| 402 | Verified company payment is required. | Review the company’s current billing/access state. |
| 403 | Current scope, company, service, portal or origin policy denies access. | Review the required permission; requesting a scope alone cannot add access. |
| 404 | Unknown or unavailable route/resource. | Use the documented path and an assigned company/record. |
| 405 | Unsupported method. | Use the method advertised by the endpoint. |
| 409 | Conflicting state or an idempotency conflict where applicable. | Read the current state and resolve the conflict. |
| 413 /415 | Body too large or unsupported media type. | Send bounded JSON for REST; form encoding for OAuth. |
| 429 | A rate/cap allowance is exhausted where enforced. | Respect Retry-After when returned; do not invent a guaranteed global rate. |
| 502 /503 | Unexpected upstream response or temporary service failure. | Use bounded retries for reads. Reconcile uncertain writes before repeating. |
Explicit boundaries
| Boundary | Limit |
|---|---|
| REST JSON request | 24,000 bytes, uncompressed |
| Company, connection, portal and task lists | 200 returned items maximum |
| Job lists | 100 returned items maximum |
| New verification jobs | 30 per company per minute; other paid-period allowances can apply |
| Access token | 300 seconds |
| Authorization grant | 30 days |
No query, cursor or pagination parameters in v1. page.mayHaveMore is conservative when a cap is reached; it is not an exact total.
Only verification accepts Idempotency-Key. Task creation has no idempotent retry guarantee. Read current records after a lost mutation response.
Version 1 does not accept query parameters or pagination offsets. A capped list reports its limit, returned count and whether more records may exist. Do not display a truncated result as a full company export.
JSON objects reject unsupported fields and duplicate keys. Paths use the documented identifiers; encoded path components and trailing slashes are not accepted for REST. API calls use Bearer tokens, never website cookies.