Errors & rate limits
Use structured errors and the operation’s HTTP response contract.
Read the contract, not the message
Operation references include committed response statuses, descriptions, and error schemas. Branch on stable error codes and status rather than free-form messages. Authentication failures, denied authority, version mismatch, invalid cursors, and idempotency conflicts need different recovery actions.
Retry with a bound
Honor Retry-After when supplied. Back off on throttling and transient dependency failures; do not retry authorization denials or malformed requests unchanged. A planned contract or capability_unavailable response is not an invitation to probe alternate routes.
Request & correlation IDs
Use the accepted x-request-id and x-correlation-id formats from the reference when provided. Keep returned identifiers for support alongside the product, revision, operation, status, and timestamp. Never include raw credentials, private customer data, or payment payloads in a support ticket.