Errors and retries

What an error looks like

Every error has the same shape:

{
  "error": {
    "code": "content_too_long",
    "message": "X (Twitter) allows 280 characters — this one is 300",
    "field": "channels[1].blocks[0].content",
    "requestId": "req_a8b0c1d2-3e4f-5678-9abc-def012345678"
  }
}

Status codes

Common error codes

The interactive reference lists every code.

Idempotency: safe retries

Networks fail. If your request times out, you don't know if Bulkit got it. If you just retry, you might publish the same post twice.

To stop this, send an Idempotency-Key header on every request that changes something (POST, PUT):

curl -X POST "$BULKIT_URL/posts" \
  -H "x-api-key: $BULKIT_API_KEY" \
  -H "Idempotency-Key: 5f1c7e0a-3b2d-4c8e-9a61-2e7d4b9f0c13" \
  ...

How it works:

• Use a new unique value (a UUID is perfect) for each new action.
• When you retry the same action, send the same key. Bulkit returns the first answer and does not do the work twice.
• Keys are kept for 24 hours, and can be up to 255 characters.

What happens after an error:

• 4xx error → nothing was saved. Fix the request and retry — you can keep the same key.
• 5xx error → part of the work may be done. Retrying with the same key returns the same error. Check what exists with GET /posts/{id} or GET /posts, then continue with a new key.

Getting help

Include the requestId from the error (or the x-request-id response header) when you contact support. It lets us find your request right away.