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.