NORMAN DEVELOPERS
API errors, retries and support
Resolve Norman API authentication and validation errors, handle rate limits and write retries, and request integration support.
Errors, limits & retries
| HTTP status | What to do |
|---|---|
| 400 / 422 | Inspect validation details, correct the field or document state, then retry. |
| 401 | Check the Bearer header, expiry and revocation. Replace an invalid key. |
| 403 | Check scopes, company, creator access and account or plan requirements. API keys only support the listed public operations. |
| 404 | Check the resource ID and path. The resource may no longer exist or be unavailable to the caller. |
| 429 | Wait for Retry-After, then retry with backoff. The default limit is 120 accepted requests per minute per key; deployment settings may change it. |
| 5xx / timeout | Retry reads with exponential backoff and jitter. Before retrying a write, check whether it already succeeded. |
{
"code": "api_key_scope_required",
"detail": "The API key does not have the required permission."
}Error bodies vary: authentication errors use detail, key permission errors also include code, field validation can return a field-to-errors object, and service errors may use serviceError. Keep the full response body when diagnosing a failed request, and remove credentials from logs.
There is no general public idempotency-key guarantee. Persist returned IDs, avoid blindly retrying creation or email operations, and reconcile a timeout before sending the same write again.
Version & support
This documentation covers the /api/v1 public contract. If you need an OpenAPI JSON file for your integration, contact support.
September 2026 · contract 1.1: document OCR and batch processing, structured imports, supporting files, product catalog, invoice PDF/XML, payment matching, contract proposals and recurring-series cancellation. Existing keys retain their configured scopes; each operation lists the permissions it requires.
The base URL connects to your real Norman company. Ask Norman support about a separate test company or test access before designing a workflow that changes business records. For help, use Support inside Norman and include the method, path, response status and a redacted error body.