Capture API error reference
Understand supported status codes and the safe client response.
- For
- Integration developers and support owners
- Owner
- Integration engineering
- Outcome
- Classify the API failure and choose a safe correction, retry, or support path.
- Last verified
- 2026-08-30
- Next review
- 2026-11-28
- Status
- supported
Treat the HTTP status, safe error code, request identifier, and idempotency key as the integration evidence. Do not log secrets or complete customer payloads.
Status code actions
| Status | Meaning | Client action |
|---|---|---|
| 400 | The request is invalid or outside the supported schema. | Correct the request before retry. |
| 401 | The key, secret, active state, or client scope is not accepted. | Repair or replace the server-side client. |
| 409 | The idempotency key conflicts with prior work. | Inspect the prior result before a new request. |
| 429 | The client rate limit is reached. | Wait and use bounded backoff. |
| 503 | The capture service is temporarily unavailable. | Retry safely with bounded backoff. |
Safe logs and support
- Log the endpoint, status, safe code, request identifier, attempt number, and final outcome.
- Redact authentication headers and unnecessary customer fields.
- Contact support with the client name, time, endpoint, safe status details, and checks completed.
Avoid harmful retries
- Do not retry a 400 response without changing the request.
- Do not generate a new idempotency key only to bypass a 409 response.
- Do not retry indefinitely after 429, 503, or a network timeout.
- Keep unresolved work visible for review.