Errors

Return standard HTTP status codes. HunterAI’s behaviour for each is fixed and listed below.

Error body shape

On any error, return a JSON body with an error string. HunterAI reads it into the failure detail it records for the sync:

{ "error": "invalid token" }

The body is optional — HunterAI falls back to the status code if it is absent or not JSON — but a clear message makes failures easy to diagnose. Only the first 300 characters are kept.

Status codes

Status	HunterAI’s reaction
`200`	Success. The `data` page is ingested.
`401`	Auth failure, no retry. The entity fails immediately. Because the token is used for every entity, all entities fail the same way and the sync is reported failed.
`404`	Endpoint not implemented. On an optional endpoint → skipped cleanly (0 records, still success). On a required endpoint → the entity fails.
`429`	Rate limited, retried. Honours `Retry-After`, otherwise backs off exponentially. Up to 5 retries, then the entity fails. See Rate limits.
`5xx`	Server error, retried. Exponential backoff, up to 5 retries, then the entity fails.
other `4xx` (e.g. `400`, `403`)	Hard failure, no retry. The entity fails immediately.

“The entity fails” means that one entity (e.g. /leads) is marked failed for the run; entities that already committed stay committed. See Partial success.

401 Unauthorized

{ "error": "invalid or expired token" }

No retry — HunterAI stops the entity the instant it sees 401.
Nothing from an unauthenticated call is ingested.
Every entity in the run hits the same 401, so the whole sync ends failed.

What the business owner sees: the connection’s sync is marked failed with an authentication error. The fix is to update the token on the connection (see Authentication → Rotating) and re-run the sync.

404 Not Found

404 is how you declare an optional endpoint unimplemented.

// GET /calls → 404
{ "error": "calls not implemented" }
// Result: calls entity = success, 0 records. Sync still succeeds.

// GET /pipelines → 404
{ "error": "not found" }
// Result: pipelines + stages entities fail. Sync reported failed.

Do not return 404 for an implemented endpoint that simply has no data — return 200 with { "data": [], "has_more": false } instead. A 404 on a required endpoint is read as “not implemented” and fails the entity.

429 and 5xx errors

Both are treated as transient and retried up to 5 times before the entity fails.

429 — HunterAI waits for the larger of your Retry-After header (seconds, floored to 1s) and an exponential backoff (1, 2, 4, 8, 16 s).
5xx — HunterAI backs off exponentially (1, 2, 4, 8, 16 s) and retries.

If the endpoint is still failing after the retries, that entity is marked failed and the rest of the sync continues.

Other 4xx — hard failure

400, 403, 422, and any other 4xx that is not 401, 404, or 429 fail the entity immediately with no retry. Reserve these for genuine client errors; do not use them for throttling (use 429) or transient issues (use 5xx).

Operations

Release notes

Error body shape

Status codes

401 Unauthorized

404 Not Found

429 and 5xx errors

Other 4xx — hard failure

​Error body shape

​Status codes

​401 Unauthorized

​404 Not Found

​429 and 5xx errors

​Other 4xx — hard failure

Error body shape

Status codes

401 Unauthorized

404 Not Found

429 and 5xx errors

Other 4xx — hard failure