Developers

Idempotency

Generating codes is the one request you must never accidentally repeat: a duplicate job would create a second set of valid codes. An idempotency key makes retries safe.

How it works

Send an idempotencyKey (8 to 120 characters) in the body of POST /v1/codes/generate. If your company has already created a job with the same key, the API returns that existing job’s jobId and status instead of starting a new one.

shell

curl -X POST https://api.credchek.com/v1/codes/generate \
  -H "X-Api-Key: $CREDCHECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batchId": "BATCH_ID",
    "quantity": 250000,
    "codeType": "qr",
    "idempotencyKey": "plant-2-B2026-014-run-1"
  }'

Choosing a key

Derive it from the real-world action, for example your production order number and run. The same order must always produce the same key.
Use a new key only when you genuinely want another set of codes, such as a second run for the same batch.
Keys are scoped to your company, so they can’t collide with another company’s keys.

When to retry

If a generate request times out or returns 503, send it again with the same key. You will either start the job or get the one that was already created. Without a key, check GET /v1/codes/jobs before trying again.

With the SDK

typescript

const { jobId } = await cc.codes.generate({
  batchId,
  quantity: 250000,
  codeType: 'qr',
  idempotencyKey: `${productionOrder}-run-${run}`,
});
const job = await cc.codes.jobs.waitForCompletion(jobId);

Next: Webhooks