Skip to main content
Idempotency lets you retry a POST /humanize request without creating a second job. When a request times out or a connection drops, you often can’t tell whether the server received it. Retrying blindly risks submitting the same text twice, which creates a duplicate job and charges API words a second time. An idempotency key removes that risk: Wibble recognizes the repeated request and returns the original job instead of starting a new one.

​
The Idempotency-Key header

To make a submission retry-safe, send an Idempotency-Key header on POST /humanize. The key is a string of up to 256 characters that you choose. Generate one key per logical request and reuse it across every retry of that request. A version 4 UUID works well because it’s unique without coordination. 
Idempotency-Key: 3f9a1b6c-2d4e-4a7f-8c10-9e2b5d7a1f00
The key identifies the request, not the text. Use a fresh key for each new submission you want to process, even when the text is identical.

​
Behavior

Wibble compares the key and the request body to decide how to respond.
KeyBodyResponse
NewAny202 — a new job is created.
ReusedIdentical200 — the original job is returned, with no new job and no additional words reserved.
ReusedDifferent (within 24 hours)409 idempotency_conflict.
A successful retry returns HTTP 200 rather than 202 because the job already exists. The job object is the same one your first request created, so you can read its id and status exactly as you would on the first call.

​
Conflicts

If you reuse a key with a different body within the retention window, Wibble returns 409 idempotency_conflict. This protects you from accidentally attaching two different submissions to the same key. The response names the job the key already belongs to and when the key frees up. 
{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request body."
  },
  "existing_job_id": "7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "expires_at": "2026-06-15T12:00:00.000Z"
}
To resolve a conflict, send the request with a new idempotency key, or retry with the original body that the key was first used for.

​
Retention

Wibble retains each idempotency key for 24 hours, starting from the first request that used it. During that window, a matching retry returns the original job. After it expires, the key is forgotten: the same key with the same body starts a new job, and any prior conflict clears.

​
Example

This submit includes an Idempotency-Key. If the call fails partway, you can run the exact same request again and get the same job back rather than a duplicate. 
curl https://wibble.ai/api/v1/humanize \
  -H "Authorization: Bearer wib_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9a1b6c-2d4e-4a7f-8c10-9e2b5d7a1f00" \
  -d '{"text": "The mitochondria is the powerhouse of the cell."}'
The first request returns HTTP 202 and creates a job: 
{
  "id": "7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "status": "queued",
  "mode": "humanize",
  "input_words": 9,
  "words_reserved": 9,
  "words_charged": 9,
  "status_url": "https://wibble.ai/api/v1/humanize/7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10",
  "current_stage": "detecting_language",
  "detected_language": null,
  "created_at": "2026-06-14T12:00:00.000Z",
  "completed_at": null
}
Run the same call again with the same key and body, and Wibble returns the same 7b42f1d6-0a8c-4e8f-9a21-c6d9f47c2b10 with HTTP 200. No second job is created, and no additional words are reserved.
Set the idempotency key before you make the request, not after a failure. If the first attempt never returns, you still hold the key needed to retry safely.

Submit a job

Every request option for POST /humanize, including the Idempotency-Key header.

Errors

The idempotency_conflict response and the full error reference.