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.

Rate limiting policy

Our API is subject to a rate limiting policy designed to maintain optimal performance and ensure fair usage. This policy restricts the number of requests to 100 per minute. Once this threshold is reached, the API will respond with an HTTP status code 429. After one minute, the request count resets, allowing you to resume your activities. This policy ensures a smooth and reliable experience for all users.


All endpoints must include the API version in the resource path. If this is not included then a 404 – Not Found error will be raised.

We will increment our API version when we release breaking changes that are not backwards compatible.

Breaking Changes

The following are not considered to be breaking changes:

  • Adding new resource endpoints
  • Adding new HTTP methods to an existing resource endpoint
  • Adding new fields to responses objects
  • Adding optional fields to requests (or fields with defaults)

Please ensure that your system can accommodate these changes without any issues.

Breaking changes may include:

  • Changing/removing fields
  • Changing resource paths

Sunsetting & Deprecation

When new versions of the API are released, the previous version will be marked as deprecated. It will also be announced via the Changelog and by email.

It is recommended to move over to the new version as soon as possible.

The previous version will continue to be supported for a period of time after the new version is released to allow API clients time to migrate.

What’s Next