# DecisioQ error and recovery reference

Always capture the HTTP status, response JSON, `requestId`, and your `X-Correlation-Id`. Do not log credentials or bearer tokens.

| HTTP | Meaning | Client action | Billed |
|---:|---|---|---|
| 400 | Malformed JSON, missing field, unsupported value, or validation failure | Correct the request; use `/api/v1/validate` before `/decide` | No |
| 401 | Token absent, expired, invalid, or issued for the wrong audience | Obtain a new token for `vinquery:api:decisioq`, retry once | No |
| 403 | Authenticated consumer is not permitted | Do not retry; contact support with request ID | No |
| 404 | Endpoint or referenced decision/profile was not found | Verify URL and identifiers | No |
| 409 | Request conflicts with current resource/configuration state | Refresh discovery data and reassess request | No |
| 415 | Content type is unsupported | Send `Content-Type: application/json` | No |
| 422 | JSON is valid but the decision inputs cannot be processed | Correct business values or constraints | No |
| 429 | Rate or quota limit reached | Honor `Retry-After` when present; use exponential backoff and jitter | No |
| 500 | Unexpected server failure | Retry only idempotent discovery calls; contact support before retrying a billable decision repeatedly | No |
| 502/503/504 | Dependency unavailable or request timed out | Retry with bounded exponential backoff and jitter | No successful decision charge |

## Retry policy

- Retry authentication once after a 401, using a newly acquired token.
- Retry GET operations up to three times for 429/502/503/504.
- Do not automatically repeat `POST /api/v1/decide` unless the service confirms whether the original request completed. Supply a unique correlation ID for investigation.
- Never retry 400, 403, 404, 409, 415, or 422 without changing the request or resolving the identified condition.

Error response shapes can contain additional diagnostic fields. Clients should ignore unknown properties for forward compatibility.