> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paraform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error envelope, HTTP status codes, and error types.

Every error response uses the same envelope:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid request",
    "request_id": "req_3f9c2a7d0b8e4f1a9c6d5e2b7a1f0c3d",
    "details": {
      "formErrors": [],
      "fieldErrors": { "email": ["Invalid email"] }
    }
  }
}
```

| Field | Description |
| - | - |
| `type` | The error category (see the table below). Branch on this, not on `message`. |
| `message` | A human-readable explanation. Don't parse it. |
| `request_id` | The same value as the `X-Request-Id` response header. Quote it when you contact Paraform. |
| `code` | Optional, more specific code. Present only on some errors. |
| `details` | Optional, structured detail. For validation errors it holds `formErrors` and per-field `fieldErrors`. |

## Status codes

| Status | `type` | Meaning | Retry? |
| - | - | - | - |
| `400` | `invalid_request_error` | The body or a parameter is malformed or has an invalid value. `details` names the fields. | No. Fix the request. |
| `401` | `authentication_error` | The API key is missing, invalid, expired, or revoked. | No |
| `403` | `permission_error` | The key lacks a required scope, or the action isn't permitted for this key or account (the message says why). | No |
| `404` | `not_found` | Unknown route, or a resource that doesn't exist **or isn't yours**. The API doesn't tell the two apart. | No |
| `409` | `idempotency_error` | An `Idempotency-Key` conflict (see [Idempotency](/idempotency)). | After the first attempt finishes |
| `413` | none | The request body is over 12 MB. This response has no envelope and no request id. | No |
| `429` | `rate_limit_error` | Rate limit exceeded (see [Rate limits](/rate-limits)). | After `Retry-After` seconds |
| `500` | `api_error` | Internal error. The message is always generic. | Yes, with backoff (and the same `Idempotency-Key` where supported) |

Treat any other `5xx` as transient and retry with exponential backoff.

## Per-item results

Batch endpoints usually return `200` even when some items fail, so one bad record doesn't fail the whole request. Check each item:

* `POST /talent-network/candidates/submit-bulk` returns `items[].status` (`queued`, `rejected`, or `deduplicated`), with `items[].errors[].code` on rejected items.
* `GET /talent-network/batches/{batchId}` reports asynchronous ingestion failures in `items[].errorCode`.
* `POST /talent-network/candidates/off-market`, `/re-enable`, and `/preferences/lookup` return `results[].ok` and `results[].status`.

Only a structurally invalid request (wrong JSON types, too many items) fails a whole batch call with `400`. See [Submit candidates](/agency/guides/submit-candidates) for the submission error codes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.