HTTP Statuses

Along with the HTTP methods that the API responds to, it will also return standard HTTP statuses, including error codes.

Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with SafetyWing's servers.

HTTP Status code	Summary
200 - OK	Everything worked as expected.
400 - Bad Request	The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized	No valid API key provided.
403 - Forbidden	The API key does not have permissions to perform the request.
404 - Not Found	The requested resource does not exist.
405 - Not Allowed	Method not allowed.
429 - Too Many Requests	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors	Something went wrong on SafetyWing’s end.

Error codes

The API uses conventional HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error caused by the request (e.g. missing parameter, invalid
format, resource not found). Codes in the 5xx range indicate a server-side error — these are rare, and if persistent, please contact support.

Error responses follow a consistent JSON format:

{
  "code": "param_validation",
  "message": "dateOfBirth must be in yyyy-MM-dd format"
}

Error code		Description
bad_request	400	The request was unacceptable - often due to a missing required parameter or an invalid value (e.g. wrong date format). Check the response message for details.
no_valid_api_key	401	No valid API key was provided. Check that the X-API-KEY header is set correctly.
api_not_configured	403	API integration is not enabled for the endpoint used. Contact our support team to get access.
api_integration_disabled	403	API key is valid but the integration is temporarily disabled. Contact our support team for more information.
not_found	404	The requested resource was not found. Verify the ID or path is correct.
internal_server_error	500	An unexpected server error occurred. These are rare — if the problem persists, please contact support.

▎ Note: The error codes listed above are the most common ones, but the API may return additional error codes depending on the specific endpoint and context. Always check the code and message fields in the error response for the most accurate information about what went wrong.