Error reference

REST errors use the same envelope as successful responses, with success: false and an appropriate HTTP status code. MCP tool errors use a different format; see MCP.

Standard error envelope

{
  "success": false,
  "message": "Human-readable error message",
  "data": {
    "error_code": "BAD_REQUEST",
    "details": {}
  }
}

error_code identifies the error category. details contains additional information when available. Check the HTTP status and error code rather than matching message text.

Validation errors

Missing required fields, incorrect types, and titles longer than 255 characters return 400 Bad Request, with error_code: "BAD_REQUEST". Multiple validation messages are joined with ; .

{
  "success": false,
  "message": "title should not be empty",
  "data": {
    "error_code": "BAD_REQUEST",
    "details": {}
  }
}

Business validation also returns 400, with error_code: "VALIDATION_ERROR": for example, an incomplete profile import, an invalid or unreachable company URL, or an invalid cover letter date.

Unknown request body fields are stripped. Duplicate document titles are resolved by adding a suffix such as _1; they do not produce a conflict error.

HTTP status codes

Rate limit errors

{
  "success": false,
  "message": "Too many requests. Please try again later.",
  "data": {
    "error_code": "RATE_LIMIT_EXCEEDED",
    "details": { "retry_after": 45 }
  }
}

Wait for the Retry-After duration in seconds before retrying. See Rate limiting for limits and headers.

Creation is not idempotent. If a connection fails after sending a create request, the job may already have been queued and charged. Do not automatically repeat creation after an ambiguous failure; check the dashboard first. Status reads can be retried with backoff.