Interview100x partner API v1
Errors
Every error code the partner API answers, what it means and what to do about it.
Every error answers the same envelope:
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "details": { "field": "job.country" } } }Branch on code. A 429 carries Retry-After (seconds).
| Status | Code | What it means | What to do |
|---|---|---|---|
| 400 | IDEMPOTENCY_KEY_REQUIRED | This write route needs an Idempotency-Key header and none was sent. | Send a unique Idempotency-Key (1–255 characters) per operation you mean, and reuse it only to retry that operation. |
| 401 | PARTNER_KEY_INVALID | The Authorization header is missing, or the partner key is unknown, revoked or expired. | Send Authorization: Bearer <key> with an active partner key; ask your Neural Bits contact for a new one. |
| 403 | PARTNER_SCOPE_MISSING | The partner key is valid but lacks the scope this call needs. | Ask for a key with the scope named in the message. |
| 403 | TEST_MODE_ONLY | A test key touched a live object, a live key touched a test object, or test mode is turned off. | Use the key of the same mode as the object (test ids start with role_test_, inv_test_, rep_test_, pi_test_); for a test key, ask for test mode to be turned on. |
| 404 | NOT_FOUND | No object with that id exists for your workspace or partnership. | Check the id; objects of another workspace, partnership or mode are never visible. |
| 409 | CONFLICT | The object is not in a state that allows this change (the message says which). | Read the object, then retry when its state allows the change; a retry_after_seconds detail says when. |
| 409 | IDEMPOTENCY_CONFLICT | The Idempotency-Key was already used with a different body or on another object. | Use a new key for a new request; reuse a key only to retry exactly the same request. |
| 409 | IN_PROGRESS | The first request with this Idempotency-Key is still running. | Wait for Retry-After and retry with the same key; you will get the first request's answer. |
| 409 | WEBHOOK_LIMIT | You already have the maximum number of webhook endpoints. | Delete an endpoint you no longer use, then subscribe again. |
| 422 | PRACTICE_COUNTRY_NOT_SUPPORTED | The job's country is in the EU/EEA or outside the countries Interview100x practice is offered in. | Practice can't be offered for this job; don't retry with the same country. |
| 422 | VALIDATION_FAILED | The request is not valid; details.field names the first field that failed. | Correct the named field and send the request again. |
| 422 | WEBHOOK_URL_INVALID | The webhook address is not a public https:// URL. | Use an https:// address on the public internet, without credentials in it. |
| 429 | INTEGRATION_RATE_LIMITED | This key sent more requests in the last minute than its limit allows. | Wait for the number of seconds in the Retry-After header, then retry; spread bursts out. |
| 429 | RATE_LIMITED | Too many requests of this kind in a short time. | Wait for Retry-After (when present) and retry with backoff. |
| 500 | INTERNAL | Something failed on our side. | Retry with the same Idempotency-Key (where the route takes one); contact support with the time of the call if it keeps failing. |
| 503 | VENDOR_UNAVAILABLE | A service we depend on did not answer in time. | Retry with backoff; nothing was changed when this is returned. |