All APIs return response in application/json content type. e.g.
{
"message": "Trip Plan Request Created"
}If an API response data that you have requested i.e. details on an item, list of items, this data will be present in the data property of the json response object.
{
"data": {
"id": 1,
"name": "Sembark User"
}
}If an API responses with a list of items, this data property will be an array of items.
{
"data": [
{
"id": 1,
"name": "Sembark User"
}
]
}Error Responses
When integrating, we should always first handle the errors. Sembark APIs provides a clean interface for error responses. All error responses include a status_code and a message key for the error name. The same status code is also as the HTTP Status code for better checking.
type ErrorResponseBody = {
status_code: string;
message: string;
};There may be other properties in the response body for some specific error responses e.g. 422. Bellow are the sample error response for different cases.
CAUTION
When checking for the response status, you should only use the status_code property, NOT the message as the message content is subjected to change.
401 - Unauthenticated
Returned when access token is missing or is invalid.
{
"status_code": 401,
"message": "Unauthenticated."
}422 - Unprocessable Entity
All the API endpoint have strict validation rules for request body. For example, if you don't pass a name parameter in request parameter and it is required by the endpoint, then you will receive the validation error for this attribute.
You will receive an array of errors per invalid field.
type ErrorResponseBody = {
status_code: 422;
message: string;
errors: Record<string, string[]>;
};Here is a sample error response when name and email have failed the validation rules for a given API endpoint.
{
"status_code": 422,
"message": "The name field is required (and 2 more)",
"errors": {
"name": ["The name field is required"],
"email": [
"The email field is required",
"The email should be a valid email address"
]
}
}404 - Unprocessable Entity
Returned if the requested resource doesn't exists
{
"status_code": 404,
"message": "The requested resource doesn't exists."
}429 - Too Many Requests
If you send too many requests in a given amount of time, you will receive this error response.
{
"status_code": 429,
"message": "You have exceeded the API rate limit. Please try after some time."
}NOTE
You can check the retry-after header in the error response which indicates how long to wait before making a new request.
405 - Method Not Allowed
If the request method (GET/POST/PATCH/DELETE) is not supported on the requested api endpoint, you will receive this error response.
{
"status_code": 405,
"message": "The GET method is not supported for this route. Supported methods: POST."
}500 - Internal Server Error
If you receive this error response, please contact us as support@sembark.com.
{
"status_code": 500,
"message": "Unexpected '(', expecting ',' or ';' at the end of line 404"
}