Handling errors is a very important part in designing and building your API. Use HTTP status codes and clear messages to indicate errors.

MUST use HTTP methods correctly [49]

The HTTP verbs which can be used are GET, POST, PUT, PATCH, DELETE, OPTIONS and HEAD. API calls made from the browser often first send an OPTIONS call to the API. The API responds with the possible communication options like the supported HTTP verbs, headers etc. Therefore we make our APIs support OPTIONS calls.

In this table, all relevant HTTP status codes are displayed. Because we want to keep things simple, we only use the most well-known codes in our APIs. The API will usually just return the status code that comes back from the backend, so it is important to use the correct codes in the backend as well!

HTTP Status code	Status formal description	When to use	set by Gateway	Set by Backend
2xx	Success
200	OK	The API call is handled successfully and will process the request.	No	Yes
201	Created	The entity is created in the backend.	No	Yes
202	Accepted	The request has been accepted for processing, but the processing has not been completed.	No	Yes
204	No Content	The server has fulfilled the request but does not need to return an entity-body, and might want to return updated metainformation. The response MAY include new or updated metainformation in the form of entity-headers, which if present SHOULD be associated with the requested variant.	No	Yes
4xx	Client Error
400	Bad Request	The API call is unsuccessful. The request could not be processed. This also applies to functional errors.	No	Yes
401	Unauthorized	The API call is unsuccessful. The caller could not be identified. This is an error that is thrown when an invalid API key is used.	Yes	Yes
403	Forbidden	The API call is unsuccessful. The caller could not be identified.	Yes	Yes
404	Not Found	The requested resource (URL) could not be found.	Yes	Yes
405	Method Not Allowed	The API is called with a method that is not supported/allowed for instance a POST is called where only GET is supported.	No	Yes
409	Conflict	The request could not be completed due to a conflict with the current state of the resource.	No	Yes
415	Unsupported Media Type	The API call is unsuccessful. The Content-type http header has the wrong value.	No	No
429	Too Many Requests	The API call is unsuccessful. The number of requests that was assigned to this API/user was exceeded (quota violation or Spike arrest).	Yes	No
5xx	Server Error
500	Internal Server Error	The API call is unsuccessful because the backend returned an error. (Backend crash).	No	Yes
502	Bad Gateway	The API call is unsuccessful because the backend acted as a proxy and received a response it could not process.	No	Yes
503	Service Unavailable	The API call is unsuccessful because the backend is temporarily unavailable. A retry could be done.	No	Yes
504	Gateway Time-out	The API call is unsuccessful because the backend did not respond within the relevant timeframe.	No	Yes

MUST use standard error model [50]

Always give a clear descriptive error message in the body that the API returns in case of an error. To stick to the REST principles, this should be in JSON format.

Example(s):

{ 
  "errors": [
    {
      "code": "403",
      "property": "SAP Klasse ZCL_REST_ISU_KLANT_RESOURCE",
      "message": "Forbidden. No appropriate role"

    }
  ]
}                           

Don’t return stack traces, they may contain sensitive information.