Helping people who build on you.
WHAT THEY ASK ABOUT
Authentication failures Unexpected errors Behaviour that differs from documentation Rate limits Something that did not arrive
WHAT TO PROVIDE SO THEY ASK LESS
Visibility of their own requests and errors Delivery logs for events Clear error messages naming the actual problem
WHY SELF-SERVICE VISIBILITY MATTERS MOST
Most questions are answered by seeing the request that failed.
WHAT TO ASK FOR WHEN THEY REPORT SOMETHING
The request identifier The time What they sent What they received
WHY THE IDENTIFIER
It locates the exact occurrence in your logs immediately.
WHAT TO PROVIDE IN EVERY RESPONSE
That identifier.
WHAT TO DO ABOUT REPEATED QUESTIONS
Fix the documentation, or the interface.
WHY THE INTERFACE
A question everyone asks indicates a design problem, not a documentation gap.
WHAT TO TRACK
What people contact about, categorised.
WHAT TO PUBLISH
Common problems and their causes.
WHAT TO COMMUNICATE PROACTIVELY
Incidents Changes Deprecations
HOW
A status page, and direct notification for anything breaking.
WHAT TO MAINTAIN
A way to reach registered callers.
WHY
Without it, deprecation is impossible to do responsibly.
