Errors & idempotency · Docs | Leffel Consulting LLC

How errors are shaped (RFC 7807 problem+json), what each status means, and how to retry safely.

Error shape

Errors are returned as application/problem+json (RFC 7807):

{
  "type": "https://lcstripeapi.leffelconsulting.com/errors/stripe",
  "title": "Payment provider error",
  "status": 502,
  "detail": "Your card was declined.",
  "stripeType": "card_error",
  "traceId": "0HN7..."
}

The title and detail fields are the human-readable, load-bearing parts. Provider errors carry a distinct type URI and a stripeType; other errors use about:blank. Every failure includes a traceId, which is also returned in the X-Correlation-Id response header — include it when you contact support.

Status reference

Status	Title	When
`400`	Invalid request	A field failed validation.
`400`	Missing header	A required header is absent (e.g. `Idempotency-Key`).
`400`	No connected account	The merchant hasn’t onboarded yet.
`401`	Unauthorized	Missing or invalid API key (empty body).
`404`	Not found	Unknown `lcPaymentId` or resource.
`409`	Idempotency conflict	Key reused with a different body.
`409`	In progress	A request with that key is still processing.
`429`	Too Many Requests	Rate limit exceeded (no body).
`502`	Payment provider error	The upstream processor errored.
`500`	Internal server error	Unexpected error; includes a `traceId`.

Retrying safely

Tip

Always send an Idempotency-Key on POST /v1/payments/intents. Then a retry after a timeout or 5xx is safe — the same key + body returns the original result instead of creating a second charge.

Retry 429 and 5xx with exponential backoff.
Do not retry 400/401/404/409 without fixing the request first.
On 409 In progress, wait briefly and retry the same request.

See the full Errors reference.