# Errors, replay and retry decisions

API base: `https://api.redlineautohaus.com/api/v1/uds`.
Reference: [generated OpenAPI](https://api.redlineautohaus.com/docs/uds/openapi.json).

Errors use `application/problem+json`. Read HTTP status and the stable `code`; use `request_id` for support correlation. `field`, when supplied, identifies the invalid field. Explanations may change; do not branch on English message text. Unknown server failures have a safe temporary-unavailability response, not SQL or a stack trace.

Illustrative validation response shape (the request ID and wording below are synthetic):

```json
{
  "type": "https://api.redlineautohaus.com/docs/uds/errors/invalid_hex",
  "title": "Hex must be nonempty, contiguous, and even length.",
  "status": 422,
  "code": "invalid_hex",
  "request_id": "example-request-id"
}
```

| Status | Meaning | Client action |
| --- | --- | --- |
| 200 / 201 | Read/replay or committed creation | Save returned ID/version; read back to verify evidence. |
| 202 | Durable asynchronous intake | Save import/batch ID and poll. This is not proof every item was accepted as a message. |
| 400 | Invalid syntax/envelope, duplicate or unsafe object key | Fix the input. Do not retry unchanged. |
| 401 | Missing/invalid/expired credential | Repair authentication through the approved credential flow. Do not repeatedly submit an expired token. |
| 403 / 404 | Disallowed action, missing resource or concealed inaccessible resource | Verify scope/permissions and returned IDs without guessing other tenants' IDs. |
| 409 | Idempotency, occurrence identity or lifecycle conflict | Read original result/state. Same key cannot mean changed evidence. |
| 412 / 428 | Stale or missing version precondition where required | Read fresh metadata/ETag, reconcile and retry with the correct `If-Match`. |
| 413 / 415 | Body too large / unsupported media type | Split work within byte and record limits; use supported content type/encoding. |
| 422 | Invalid field, bytes or relationship | Correct the field. Preserve invalid source text as independent evidence if appropriate. |
| 429 | Rate, quota or capacity limit | Respect `Retry-After`, reduce offered load and use bounded retries. |
| 503 / temporary gateway failure | Temporary service/infrastructure problem | Retry within a deadline using the same idempotency key/body; check status after uncertain completion. |

## Two independent replay guarantees

`Idempotency-Key` is scoped to authenticated owner, principal and route. The same key and semantically equivalent body return the original committed result; a changed body conflicts. JSON whitespace/key order are not new meaning; arrays remain ordered, and missing is distinct from null.

A message also has `client_namespace`, `session_id` and `external_record_key`. Their occurrence identity is independent of import ID and protects an already accepted observation beyond the HTTP response-cache window. Identical bytes in a different source occurrence require a different occurrence key and remain distinct observations.

Keep the same HTTP key/body after network loss. Generate a new key only for a genuinely new operation or explicit correction. Do not use timestamps/random keys on every automatic retry. Retain client resume metadata if your deadline expires.

## Validation examples

- `"payload_hex": "22F18"`: odd length; reject rather than append a zero.
- `"payload_hex": "22 F1 86"`: spaces are source formatting, not canonical hex. Preserve the excerpt; submit known bytes as `22F186`.
- Both `payload_hex` and `payload_base64`: ambiguous encodings; supply exactly one.
- `"representation": "complete"` with empty bytes: reject. Choose partial/unavailable only when supported by actual evidence.
- Partial segments with overlapping known byte ranges: reject; preserve unresolved source fragments without invented offsets.
- `scope_id`, `created_by` or a contributor-supplied verified state: server-owned fields/permissions cannot be set by input JSON.
- An endpoint from another session/scope: reject the relationship. Never silently reassign it.

## Batch failures

A malformed envelope is rejected before message processing. A valid envelope may contain invalid items: inspect individual `created`, `existing`, `rejected` and cancellation outcomes plus aggregate counts. A `completed_with_errors` batch retains its accepted messages. Correct rejected items deliberately; do not replay an entire mixed batch under new occurrence identities.

Cancellation stops remaining work where possible, not committed observations. Finalization seals import intake, not instant completion. Query the documented status endpoints after uncertain finalize/cancel results.

## Safe diagnostics

Report route template, HTTP status, safe code, request ID and import/batch ID where appropriate. Do not log bearer tokens, source bodies, customer identifiers, raw diagnostic bytes or private artifact transfer URLs in ordinary error telemetry.