The Company Matching API uses standard HTTP status codes. Most error responses include a JSON body with a detail field.
Error envelope
Match on status codes in your error handling, not on the exact detail string — wording can change between releases.
429 is the exception. Rate-limit responses from SlowAPI typically use an error key instead of detail. Read both keys when logging.
Status code matrix
Retrying
Retry 429, 500, and 503 with exponential backoff:
Add random jitter (0–500 ms) so concurrent clients do not synchronise retries.
Do not auto-retry 401, 404, 409, or 422 with the same payload. Fix the key, id, timing, or body first.
Common scenarios
401 on every call
Almost always a missing Authorization header, a JWT instead of a dm_live_… key, or a revoked key.
422 on batch submit
Either a company object failed validation (for example empty input_name), the list exceeds 1,000 companies, or callback_url / webhook_secret failed validation.
409 on results
You called GET /match/batch/{job_id}/results while the job was still queued. Poll GET /match/batch/{job_id} until status is running, completed, or failed, then fetch results.
Client timeout on POST /match
Matching can take tens of seconds on a cold path. Set the client timeout to at least 60–120 seconds before treating the call as failed. 
