Skip to Content
ConceptsIdempotency

Overview

Network failures, timeouts, and infrastructure issues are inevitable in distributed systems. Without idempotency, retrying a failed request might create duplicate candidates, send duplicate invitations, or trigger duplicate status changes.

The Celper AI API supports idempotent requests so you can safely retry write operations without worrying about duplicate side effects. If the server already processed a request with the same idempotency key, it returns the cached response instead of executing the operation again.

How It Works

Include the Idempotency-Key header with a unique string on any supported request. A UUID v4 is recommended.

  1. The API receives your request and checks if the Idempotency-Key has been seen before.
  2. First time — The request is executed normally. The response is cached and associated with your key.
  3. Subsequent requests with the same key — The API returns the cached response without re-executing the operation. The HTTP status code and body are identical to the original response.

Cached responses are stored for 24 hours. After the TTL expires, the key can be reused and will be treated as a new request.

Supported Endpoints

Idempotency keys are supported on the following write endpoints:

EndpointMethod
/v1/candidatesPOST
/v1/candidates/{id}/invitePOST
/v1/candidates/{id}/selectPOST
/v1/candidates/{id}/rejectPOST

GET, PATCH, and DELETE endpoints are naturally idempotent and do not require an Idempotency-Key header.

Key Requirements

  • Scope — Keys are scoped per company. Two different companies can use the same key value without conflict.
  • TTL — Keys expire after 24 hours. After expiration, the same key can be reused.
  • Format — Keys must be unique strings. UUID v4 is recommended but any non-empty string up to 255 characters works.
  • Consistency — If you reuse a key with a different request body, the API returns a 409 IDEMPOTENCY_CONFLICT error (see below).

Example

curl -X POST https://api.celper.ai/v1/candidates -H "X-API-Key: celp_your_api_key_here" -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" -H "Content-Type: application/json" -d '{
  "jobPositionId": "pos_abc123",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane.smith@example.com"
}'

Conflict Response

If you send a request with an Idempotency-Key that was already used with a different request body, the API returns a 409 Conflict:

409Idempotency Conflict

To fix this, generate a new Idempotency-Key for the different request payload.

PaginationError Handling