Responses

Response codes summary

Verb Code Reason
Any 400 Any part of the query string or body is in error
401 Invalid or missing Bearer token
403 Forbidden, only returned if there is a valid Bearer token but the actor or service does not have proper rights
404 Not found, e.g. requesting a non-existing resource-id
414 URI Too Long (larger than 2083 characters)
429 Hitting a rate limit
500 Internal server error
503 Service not available, e.g. down for maintenance
GET 200 Request for data is correct. Data is returned.
202 Accepted. See delayed operations
304 Requested data is not modified. Not including data in response.
409 Concurrency conflict
410 Gone
POST 201 Resource created
202 Accepted. See delayed operations
PUT 200 Existing resource updated
201 New resource created
202 Accepted. See delayed operations
409 Concurrency conflict
DELETE 204 Success, does not return content

Error responses

Whenever returning an error (4xx, 5xx) the API will also return an error object. The following fields are the minimum which will always be present.

{
	"error":{
		"code":"identifierStyle",
		"message":"human-readable"
	}
}

In case of validation errors of the input provided in the body, some validation error messages will be provided in the answer.

{
	"error":{
		"validationErrors":[
			"Id must be positive"
		],
		"code":"BadRequest",
		"message":"The request was invalid"
	}
}
Example: The requested resource does not exist 
{
	"error":{
		"code":"NotFound",
		"message":"No data was found for the request"
	}
}

Example: Internal server error (which should not occur) 
{
	"error":{
		"code":"InternalServerError",
		"message":"84b940b4-82ed-4c4c-a794-ecafa9c9fe26"
	}
}

More specific error handling info can be found in the Swagger section

Rate limiting

When rate limiting occurs

Rate limiting may be enforced when the system detects excessive usage, such as when requests exceed thresholds set by our server infrastructure.

If you encounter a 429 Too Many Requests error, it means you have surpassed the allowed request rate.

Fair use policy

Our platform operates on a fair use policy, ensuring all users have equal access to resources. To avoid hitting rate limits:

Distribute requests evenly over time. Implement retry logic with exponential backoff when receiving a 429 response.

What to do when you hit a 429?

If you receive a 429 error:

  • Pause your requests temporarily.
  • Adjust your request frequency to comply with fair use limits.