Idempotency

POST /v1/projects accepts an optional Idempotency-Key. Use it so a retried create does not open a second project.

Other published /v1 routes ignore this header.

Send it

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

The value is opaque. A UUID per unique create is enough. Keys are scoped to your API key — another integration can reuse the same string.

curl -s https://api-arbitr.straker.ai/v1/projects \
  -H "X-API-Key: abr_live_…" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "file=@./source.docx" \
  -F "name=Q1 handbook" \
  -F "source_language_code=en-us" \
  -F 'target_language_codes=["ja-jp"]' \
  -F 'workflow=["AI_TRANSLATION"]'

What happens

One key is one operation. The body is not inspected — reusing a key with a different file does not start a second project, and does not produce an error telling you the body changed. Treat a key as belonging to exactly one create.

Retry	Result
Key already succeeded	The original `201` replayed byte-for-byte, for 24h
Key still in flight, or outcome unknown	`409 idempotency_in_progress`
Create rejected before anything was created	Key is released — retry with the same key
No header	Every call creates a new project

The window is 24 hours, both for replaying a stored 201 and for holding a key that is in flight.

When a retry is safe

If the create was rejected before the project could exist — a validation failure such as an unknown language code, or the request never reaching the pipeline — the key is released and you can send it again with a corrected body.

Anything else leaves the key held for the full 24 hours: a timeout, a 5xx, a dropped connection, or any failure after submission has started. This is deliberate. Once submission is under way the project may already exist and be billable, so a retry must not be able to create a second one.

That means 409 idempotency_in_progress does not always mean "still running". It can also mean "the outcome is unknown and we will not risk billing you twice". If you get it and you are not simply retrying a call from a moment ago, look for the project with GET /v1/projects rather than retrying the key — the key will keep answering 409 for the rest of the day.

Limits worth knowing

If the idempotency store is unreachable the create is processed anyway, without deduplication. A retry in that window can produce a duplicate project — availability is preferred over strict deduplication here.

The 24-hour clock on a stored 201 runs from when it was stored, not from your first attempt, so a key can remain usable for up to about 48 hours from first use before it is free again.

There is one narrow case where a successful create still answers 409 on retry rather than replaying: if storing the response failed after the 201 was returned. You already have the 201; you will not be billed twice.

In progress

{
  "error": {
    "code": "idempotency_in_progress",
    "message": "A request with this Idempotency-Key is already in progress",
    "request_id": "…"
  }
}

If the first call was moments ago, wait a few seconds and send the same key again. Otherwise read the section above — the project may already exist.

Pagination

Rate limits