Errors

The Solaris API uses conventional HTTP response codes to indicate the outcome of an API request. Response codes can be grouped into the following categories:

  • 2xx: The request was successful.
  • 4xx: An error occurred due to the information provided, e.g., missing or incorrect parameters.
  • 5xx: Those errors are returned if there was an error in Solaris servers.

Solaris API error responses all follow a standard format. They include the HTTP response code, the reason for the error, and a unique ID for use with Solaris customer support.

Error response parameters

Parameter Type Description
id string Unique ID of the error. Submit this ID when filing a ticket with Solaris customer support.
status string The HTTP status code of the error.
code string Computer-readable code for error handling.
title string Human-readable generic error message.
detail string Human-readable error message containing all available details about how the error occurred.
source object An object containing information about which attribute on a model caused the error (for errors involving a model):
  • field: The specific attribute that caused the error.
  • message: Details about how the error was caused.

Example error—400 Bad Request:

Copy
Copied
{
    "errors":
    [
        {
            "id": "84b61fb9bf2117b3653a91ba9fc18d8bex",
            "status": 400,
            "code": "invalid_model",
            "title": "Invalid Model",
            "detail": "employment_status is not included in the list [\"EMPLOYED\", \"UNEMPLOYED\", \"PUBLIC_SECTOR_EMPLOYEE\", \"PROFESSIONAL_SOLDIER\", \"FREELANCER\", \"HOUSEWORK\", \"APPRENTICE\", \"MANAGEMENT\", \"RETIRED\", \"STUDENT\", \"SELF_EMPLOYED\", \"MILITARY_OR_COMMUNITY_SERVICE\"]",
            "source":
            {
                "field": "employment_status",
                "message": "is not included in the list [\"EMPLOYED\", \"UNEMPLOYED\", \"PUBLIC_SECTOR_EMPLOYEE\", \"PROFESSIONAL_SOLDIER\", \"FREELANCER\", \"HOUSEWORK\", \"APPRENTICE\", \"MANAGEMENT\", \"RETIRED\", \"STUDENT\", \"SELF_EMPLOYED\", \"MILITARY_OR_COMMUNITY_SERVICE\"]"
            }
        },
        {
            "id": "84b61fb9bf2117b3653a91ba9fc18d8bex",
            "status": 400,
            "code": "invalid_model",
            "title": "Invalid Model",
            "detail": "last_name is too long (maximum is 50 characters)",
            "source":
            {
                "field": "last_name",
                "message": "is too long (maximum is 50 characters)"
            }
        }
    ]
}

List of error codes

Most model validation errors result in invalid_model errors (as opposed to validation_error errors) and contain a message that explains the cause of the error.

note

The Solaris API will return different errors at different stages of the validation process, which may abort the process. For example, it will raise a 403 Forbidden or 404 Not Found error before validating any models. If this happens, then the API will not return any information about invalid model attributes.

Status Code JSON Code Title Detail
400 Bad Request invalid_model Invalid Model '(first_name)' can't be blank, is invalid.
... invalid_webhook_url Invalid Webhook URL Webhook URL '(https://example.com/identification)' returned invalid status ((404)). Webhook Subscription was not created
... unsafe_webhook_url Unsafe Webhook URL Webhook URL '(http://example.com/identification)' is unsafe, please provide a HTTPS URL
... validation_error Validation Error There was a validation error.
... type_error Type Error Expected (first_name) to be (String).
401 Unauthorized invalid_token Invalid Token Token is invalid.
... token_required - Bearer Token is not provided
403 Forbidden unauthorized_partner Unauthorized Partner The partner in session is not allowed to access this '(Solaris::Person)' model.
... unauthorized_action Unauthorized Action Unauthorized action '(POST)' is not allowed for '(Solaris::Person)'
... authorization_required Authorization Required Authorization is required.
... invalid_tan Invalid TAN Invalid or expired TAN for (MobileNumber) with uid: '(a0c52083…)'
404 Not Found model_not_found Model Not Found Couldn't find (Solaris::Person) for id (045ea1e0…).
405 Method not Allowed method_not_allowed Method not Allowed Only the following methods are allowed: '(OPTIONS, GET, PATCH, HEAD)'
409 Conflict record_not_unique Record Not Unique Could not save '(MobileNumber)'. '(person_id)' must be unique for '(MobileNumber)'
429 Too Many Requests too_many_requests Too Many Requests You have exceeded the rate limit for this request. The API response will contain information specific to that particular endpoint.
500 Internal Server Error generic_error Generic Error There was an error.
... invalid_json Invalid JSON The provided JSON was not properly formatted.
501 Not Implemented not_implemented_error Not Implemented Error This endpoint has not yet been implemented.
502 Bad Gateway bad_gateway Bad Gateway There was a generic error.
503 Service Unavailable connection_error Connection Error There was a connection error.
504 Gateway Timeout gateway_timeout There was a generic error.

Requesting support from Solaris

If you're encountering errors and you'd like to request support from Solaris, please pay attention to the following points:

  • Solaris needs the endpoint URL, error code, and unique request ID to handle any support requests.
  • Solaris stores logs for only 30 days.
  • Solaris doesn't store the request's payload in the logs.