API errors

Conflict

The request is valid but conflicts with the current state of the resource. The detail field says which conflict you hit.

409application/problem+json

What it means

The request could not be applied to the resource as it stands right now. The detail field distinguishes the cases: an identifier that must be unique (such as an externalProfileId) is already taken, the resource is mid-change under a concurrent request, or the resource cannot make the requested state transition from its current state.

A duplicate request whose X-Idempotency-Key is still being processed is not a conflict; it returns locked.

409 · application/problem+json

{
  "type": "https://developers.firsty.app/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "A profile with 'externalProfileId' 'customer-42' already exists"
}

How to handle it

Read detail before doing anything else. The right response depends on which conflict this is, and a blind retry loop on the wrong one will never clear.
For a uniqueness conflict, the identifier is already in use. Look up the existing resource instead of retrying the create.
For a concurrent-change conflict, wait a moment and retry; the other request finishes quickly.
For a state conflict, fetch the resource's current state first and only request transitions that are valid from it.

Idempotency, in the rate limits guide eSIM lifecycle Errors reference

What it means

How to handle it

Related