Errors - Paraform

Every error response uses the same envelope:

{
  "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).	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).	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 for the submission error codes.

⌘I