Retries and idempotency

A request can time out after Pipecorn has already queued the work and charged for it. Retrying blindly could enrich the same contact twice. Send an Idempotency-Key header on every POST and you can retry as often as you need: the work runs once.

curl https://app.pipecorn.com/api/v2/contacts/single_enrich \
  -H "X-API-KEY: $PIPECORN_API_KEY" \
  -H "Idempotency-Key: 4f1c2e9a-8a7d-4c1b-9f63-2d6e0b5a7c11" \
  -H "Content-Type: application/json" \
  -d '{"firstname": "Mathieu", "lastname": "Brun-Picard", "domain": "pipecorn.com", "enrichment_type": ["email"]}'

How it works

Generate one key per operation, such as a UUID, and reuse it for every retry of that operation. Keys are up to 255 characters.
The first request runs normally. Retries with the same key and the same body get the stored response back, with the header Idempotent-Replayed: true. Nothing runs or is charged again.
Successful responses are kept for 24 hours. A request that fails (any non-2xx answer) is not stored, so you can fix the cause and retry with the same key.
Keys are scoped to your user, or to your workspace when you call with a workspace key.
Every POST endpoint accepts the header. GET and DELETE are safe to retry as they are.

Errors

Status	`code`	Meaning
`409 Conflict`	`idempotency_key_in_use`	The first request with this key is still running. Wait for `Retry-After` seconds and retry with the same key.
`422 Unprocessable Content`	`idempotency_key_reused`	The key was already used with a different body. Generate a new key for a new operation.
`400 Bad Request`		The key is longer than 255 characters.

First steps

Building a client

Build with AI

Resources

How it works

Errors

​How it works

​Errors

How it works

Errors