API Behaviour


The Sikoia API expects and returns JSON. As such, you should add the following two headers to each API request:

Accept: 'application/json'
Content-Type: 'application/json'

API requests without authentication will also fail. The following header must be included in every request:

Authorization: 'Bearer {access_token}'

For more information on authorization read our guide here.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.


Sikoia uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Sikoia’s servers (these are rare).

Success Codes

Status CodeMeaning
200Ok – everything worked as expected
201Created – the object has been created
202Accepted – the async task has been accepted but not yet completed
204Deleted – the object has been successfully deleted

Error Codes

Status CodeMeaning
400Bad Request – The request was unacceptable, often due to a missing required parameter
401Unauthorised – Invalid or expired bearer token
403Forbidden – The client application does not have permission to perform the requested action
404Not found – The requested resource does not exist
409Conflict – The request conflicts with another request, likely due to reusing an idempotency key
422Unprocessable – Valid request that is semantically incorrect
429Too many requests – Too many requests hit the API too quickly.
5xxServer error – Something went wrong on Sikoia’s end

Generic Error Response

The Sikoia API has a generic error response which is standard across all endpoints

	"status": http_status_code,
	"type": string,
	"title" : title,
	"details": string,
	"correlation_id" : UUID

This includes the following error types:

Error TypeTitle/DetailsStatus Code
ServerErrorAPI Error - Something went wrong on Sikoia's end5xx
InvalidRequestInvalid request - a field in the request failed validation400
ResourceNotFoundResource Not Found - the requested resource could not be found404
ResourceDeletedResource Deleted - the resource at this location has been deleted404
UnprocessableRequestUnprocessable Request - the request was valid but could not be processed422
RateLimitRate Limit429
InsufficientPermissionsInsufficient Permissions403
InvalidTokenInvalid Token401
ExpiredTokenExpired Token

Correlation ID

We include a X-Correlation-Id header with all requests and responses. This is a unique ID that we use to trace any issues in our system. We also add the correlation_id in all error responses.

To make responding to support requests as quick and direct as possible, please include the Correlation ID in tickets you might raise.

What’s Next