...
HTTP status codes - Use the appropriate value amongst the following (or document in the code why an exception is needed)
- 200 - OK
- 201 - Created
- 204 - OK, no content returned (use for PATCH)
- 304 - Not Modified
- 400 - Bad Request
- 401 - Unauthorized (for unauthenticated users)
- 403 - Forbidden (for authenticated users who do not have the right permissions)
- 404 - Not Found
- 415 - Unsupported Media Type (used for PATCH if implementation is "merge patch" algorithm, and caller did not specify "application/merge-patch+json" content_type).
- 500 - Internal Server Error
- Prevent information leakage
Must: Use 404 instead of 403 when the actual existence would be leaking information that we don't want - Dave O.
Error Description
Must: Be verbose and use plain language descriptions.
- Must: Use i18n for user facing messages ("user_message" in example below)
Nice: Add as many hints as your API team can think of about what's causing an error.
Nice: Add a link in your description to more information, like Twilio does.
Error format:
developer_message (no i18n)
user_message(optional, but if provided, i18n as the expectation is that this may surface in a UI)
field_errors (if applicable)
error_code (for example: see has_access interface design /wiki/spaces/MS/pages/31687272) Include description in your REST API Docs.
Code Block { "error_code": "course_not_started" # a short string that the client can rely upon for handling different errors "developer_message" : "Verbose, plain language description of the problem for the app developer with hints about how to fix it.", "user_message":"Pass this message on to the app user if needed.", "field_errors": { "foo": { "developer_message": "", "user_message": "" } } }
...