Errors, concealment, and support
Handle stable problem responses without relying on internal implementation detail.
Problem response contract
Error responses use application/problem+json with the fields type, title, status, code, correlation_id, retryable, and errors. Like every other body, field names are snake_case. Branch on the documented HTTP status and stable code, retain correlation_id for support, and do not parse title text as a machine contract.
- retryable is always present. true means the same request may be retried after a bounded backoff; false means retrying the identical request will not succeed.
- errors is null or an object whose values are arrays of strings describing invalid input.
- 400 indicates malformed or contract-invalid input, including a missing or invalid Idempotency-Key; correct the request.
- 401 requires fresh authentication; 403 means the authenticated caller lacks current authority.
- 404 can deliberately conceal whether an operation, item, vendor, or represented context exists.
- 409 indicates state, revision, candidate, ceiling, action, cursor, or idempotency conflict; retrieve current state before deciding again.
- 422 means a semantically invalid request, such as an HPH Item Code that cannot be resolved or is inactive for mapping.
- 413 requires a smaller request. 429 requires waiting for the quota window. 503 is a bounded dependency failure.
Safe support escalation
Provide the correlation_id from the problem or successful response, the UTC timestamp, operation name, HTTP status, and stable problem code through your HPH support contact. Do not send credentials, idempotency keys, candidate tokens, complete item bodies, or complete responses.
Disclosure boundary
Responses contain only fields defined by the public response contract and permitted for the represented Company. They omit confidential matching evidence, exact scores or thresholds, credentials, and implementation details. A concealed response must not be used to infer company, application, operation, or candidate existence.