Document everything - API errors

[ionutdobre]

When it comes to documentation and also API implementation I would add something about documenting the API Errors:

• what are the controlled errors that the API can return, for example: bad parameters, field name not found, no results matched your filters, etc…
• what are the maintenance errors - example: you are (re)deploying the API so it will not be available for a short period of time
• what are unrecoverable errors - for example: database crashed

Short example of API Error documentation

In case of an error (on client or server side), the API response will contain a JSON error body that provides: a useful error message, an error code, and the URL that caused the error. For example:

{
    "errors": [
        {
            "code" : "E01",
            "message": "Bad parameters. Please check the documentation for more informations."
            "url": "https://www.example.com/api/v1/sdgs?country=ro&item=123"
        }
    ]
}

Errors dictionary

• E01 - at least one of the parameters is incorrect
• E02 - ...
• E03 - ...