Skip to content
Last updated

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

ParameterTypeDescription
idstringUnique ID of the error. Submit this ID when filing a ticket with Solaris customer support.
statusstringThe HTTP status code of the error.
codestringComputer-readable code for error handling.
titlestringHuman-readable generic error message.
detailstringHuman-readable error message containing all available details about how the error occurred.
sourceobjectAn 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:

{
    "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.

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 CodeJSON CodeTitleDetail
400 Bad Requestinvalid_modelInvalid Model'(first_name)' can't be blank, is invalid.
...invalid_webhook_urlInvalid Webhook URLWebhook URL '(https://example.com/identification)' returned invalid status ((404)). Webhook Subscription was not created
...unsafe_webhook_urlUnsafe Webhook URLWebhook URL '(http://example.com/identification)' is unsafe, please provide a HTTPS URL
...validation_errorValidation ErrorThere was a validation error.
...type_errorType ErrorExpected (first_name) to be (String).
401 Unauthorizedinvalid_tokenInvalid TokenToken is invalid.
...token_required-Bearer Token is not provided
403 Forbiddenunauthorized_partnerUnauthorized PartnerThe partner in session is not allowed to access this '(Solaris::Person)' model.
...unauthorized_actionUnauthorized ActionUnauthorized action '(POST)' is not allowed for '(Solaris::Person)'
...authorization_requiredAuthorization RequiredAuthorization is required.
...invalid_tanInvalid TANInvalid or expired TAN for (MobileNumber) with uid: '(a0c52083…)'
404 Not Foundmodel_not_foundModel Not FoundCouldn't find (Solaris::Person) for id (045ea1e0…).
405 Method not Allowedmethod_not_allowedMethod not AllowedOnly the following methods are allowed: '(OPTIONS, GET, PATCH, HEAD)'
409 Conflictrecord_not_uniqueRecord Not UniqueCould not save '(MobileNumber)'. '(person_id)' must be unique for '(MobileNumber)'
429 Too Many Requeststoo_many_requestsToo Many RequestsYou have exceeded the rate limit for this request. The API response will contain information specific to that particular endpoint.
500 Internal Server Errorgeneric_errorGeneric ErrorThere was an error.
...invalid_jsonInvalid JSONThe provided JSON was not properly formatted.
501 Not Implementednot_implemented_errorNot Implemented ErrorThis endpoint has not yet been implemented.
502 Bad Gatewaybad_gatewayBad GatewayThere was a generic error.
503 Service Unavailableconnection_errorConnection ErrorThere was a connection error.
504 Gateway Timeoutgateway_timeoutThere 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.