The answer
Yes. Validation failures, expired sessions, and insufficient permissions affect the user experience. Documenting them lets clients respond predictably instead of handling every failure as an unknown error.
What is the purpose of an API-design document?
Should an API-design document include unsuccessful responses?
More FAQs in What is the purpose of an API-design document?
They clarify field names, nesting, optional values, and expected states. Combined with written rules, realistic examples reduce the chance that the assistant invents incompatible client and server shapes.
No. Documentation describes intended rules, but the implementation must enforce and test them. Review access checks, validation, and failure behavior against the contract before considering the operation complete.
Still have questions?
Browse all our FAQs or reach out to our support team
Want to upskill yourself?
Your learning library
Small steps. Big possibilities.
Find your next course. Build something great.