Handle application/problem+json errors
Turn API, validation, permission, billing, and provider failures into actionable client behavior.
Parse non-success responses as application/problem+json with type, title, status, detail, code, request_id, and optional field errors. Route behavior from stable status and code values while displaying safe detail and preserving the request ID for support.
What this means in practice
Parse non-success responses as application/problem+json with type, title, status, detail, code, request_id, and optional field errors. Route behavior from stable status and code values while displaying safe detail and preserving the request ID for support.
Use the documented brand and account boundaries consistently across the scheduler, REST API, SDK, MCP tools, SSE consumers, and webhooks. That makes the same social operation explainable to an operator and reproducible by an integration.
Implementation checklist
Check response status and content type before parsing a success resource.
Map validation errors to the named composer fields.
Separate authentication, authorization, conflict, rate-limit, and provider outcomes.
Log request_id with your internal trace but never log secrets or raw media payloads.
Show a user action such as reconnect, edit, top up, retry later, or contact an admin.
Operational details
A 409 can indicate an idempotency conflict or state transition conflict rather than a generic server failure.
Target-level provider errors can coexist with a successful parent API response.
Safe detail is intended for client display; internal provider tokens remain excluded.
Common mistakes to avoid
- Do not retry every 4xx response.
- Do not show users a raw provider response containing implementation detail.
- Do not discard request_id when wrapping the error in your own SDK class.