Skip to Content
ConceptsError Handling

Error Response Format

All API errors follow a consistent structure. Every error response includes a machine-readable error code, a human-readable message, and a unique request ID for debugging.

{
  "success": false,
  "error": "ERROR_CODE",
  "message": "Human-readable description of what went wrong",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
FieldDescription
successAlways false for error responses.
errorMachine-readable error code. Use this for programmatic error handling.
messageHuman-readable message describing the error. Suitable for logging but not for display to end users.
requestIdUnique identifier for the request. Include this when contacting support.

HTTP Status Codes

StatusMeaning
200Success
201Created
202Accepted (async processing)
304Not Modified (ETag match)
400Validation Error
401Unauthorized
403Forbidden
404Not Found
409Conflict
429Rate Limited
500Internal Server Error

Retry Guidance

Not all errors should be retried. Follow these rules:

Never retry 4xx errors — they indicate a problem with your request that must be fixed before resending.

  • 429 (Rate Limited) — Retry after the number of seconds in the Retry-After header. Use exponential backoff for subsequent retries.
  • 5xx (Server Errors) — Retry with exponential backoff. These are transient errors on the server side.
  • 4xx (Client Errors) — Do not retry. The request itself is invalid and must be fixed before resending.

Decision flow:

Is the status code 429?
  Yes -> Wait for Retry-After seconds, then retry
  No  -> Is the status code 5xx?
    Yes -> Retry with exponential backoff (max 3 attempts)
    No  -> Is the status code 4xx?
      Yes -> Do not retry. Fix the request.
      No  -> Success. Process the response.

Request ID

Every API response — both successful and failed — includes a request ID in two places:

  1. The X-Request-Id response header
  2. The requestId field in the response body
HTTP/1.1 400 Bad Request
X-Request-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "...",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

When contacting Celper AI support about an API issue, always include the request ID. It enables the team to trace your request through the system.

Common Errors

Unauthorized (401) — The API key is missing or invalid.

401Unauthorized

Insufficient scope (403) — The API key does not have the required scope for this endpoint.

403Insufficient Scope

Validation error (400) — The request body or query parameters are invalid.

400Validation Error

Not found (404) — The requested resource does not exist.

404Not Found

Duplicate candidate (409) — A candidate with the same email already exists in the job position.

409Duplicate Candidate
IdempotencyWebhooks Guide