HTTP status codes & error handling

ZF | SCALAR follows the universal HTTP status codes. SCALAR API endpoints will not use allow specified HTTP status codes. This page explains which status codes are used and in which case they can expect them.

In case of errors, SCALAR API endpoints will also return additional error info.

HTTP status codes - correct processing

Following HTTP status codes are used by SCALAR API endpoints

HTTP code\VERB	GET	POST	PUT	PATCH	DELETE
200 (Success)	V		V	V	V
201 (Created)	V	V	V
202 (Accepted)		V			V

HTTP status codes - failure

HTTP code\VERB	VERBS	Description
400 (Bad request)	all	Request not properly formatted.
401 (Unauthorized)	all	Integrator does not have the proper credentials or invalid credentials.
403 (Forbidden)	all	Credentials are ok but integrator does not have the necessary rights to access.
404 (Not found)	all except POST	Not found the request-URI
429 (Too many requests)	all	Rate limiting - rates have been exceeded
500 (Internal server error)	all
503 (Service unavailable)	all

Extra error info in response

In case of an error, SCALAR API endpoints add extra metadata in the response. This extra information can be useful for the developer to understand what the problem is. Avoid automatically interpreting these codes as they can be susceptible to change without notification to the developer (does not follow the deprecation policy).

Example of an error response:

{
    "type": "validationException",
    "message": "The input data contains invalid fields.",
    “errors": [
        { 
            "field": "truck.lic",
            "type": "duplicateKeyDetected",
            "args": ["1-eds-845"],
            "message": "The license plate {0} is not unique."                    },
         { 
            "field": "truck.code",
            "type": "stringNumberMissing",
            "args": ["trucktruckgo"],
            "message": "Truck code {0} does not contain any number."
         }
    ]
}