Requests

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.

Responses

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 Code	Meaning
`200`	Ok – everything worked as expected
`201`	Created – the object has been created
`202`	Accepted – the async task has been accepted but not yet completed
`204`	Deleted – the object has been successfully deleted

Error Codes

Status Code	Meaning
`400`	Bad Request – The request was unacceptable, often due to a missing required parameter
`401`	Unauthorised – Invalid or expired bearer token
`403`	Forbidden – The client application does not have permission to perform the requested action
`404`	Not found – The requested resource does not exist
`409`	Conflict – The request conflicts with another request, likely due to reusing an idempotency key
`422`	Unprocessable – Valid request that is semantically incorrect
`429`	Too many requests – Too many requests hit the API too quickly.
`5xx`	Server 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 Type	Title/Details	Status Code
`ServerError`	API Error - Something went wrong on Sikoia's end	`5xx`
`InvalidRequest`	Invalid request - a field in the request failed validation	`400`
`ResourceNotFound`	Resource Not Found - the requested resource could not be found	`404`
`ResourceDeleted`	Resource Deleted - the resource at this location has been deleted	`404`
`UnprocessableRequest`	Unprocessable Request - the request was valid but could not be processed	`422`
`RateLimit`	Rate Limit	`429`
`InsufficientPermissions`	Insufficient Permissions	`403`
`InvalidToken`	Invalid Token	`401`
`ExpiredToken`	Expired 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.

Versioning

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.