Errors & idempotency

RFC 7807 problems and Idempotency-Key semantics.

Problem details

Every error response is application/problem+json, per RFC 7807: a type URI identifying the error kind, a human-readable title, the HTTP status, and a detail describing this specific occurrence.

{
  "type": "https://platform.dev/problems/validation",
  "title": "Validation failed",
  "status": 400,
  "detail": "Idempotency-Key header is required for this request"
}

Status codes

Status	Meaning
`400`	Validation failed — a required field is missing or malformed.
`401`	Authentication required — the bearer token is missing, expired, or invalid.
`403`	The client isn't allowed to do this — wrong client type (org-wide vs. programme-pinned) or wrong programme.
`404`	The resource doesn't exist, or isn't visible to this client.
`409`	Conflict — for example, an `Idempotency-Key` reused with a different request body.

Idempotency

Mutating requests (POST, PATCH, DELETE) require an Idempotency-Key header. Retry the same request with the same key and the same body, and you get back the original stored result rather than a duplicate side effect — safe to retry on a timeout or a dropped connection. Reuse the same key with a different body and the request is rejected with 409.

Keys are scoped per operation, not globally, so the same key value used against two different endpoints doesn't collide. Generate a fresh UUID for each logically distinct request:

-H "Idempotency-Key: $(uuidgen)"

One endpoint is a deliberate exception: POST /v1/simulated-spends does not take an Idempotency-Key, because each accepted call is meant to be its own distinct transaction rather than a replay-safe one — see the Quickstart.