Errors

AltScore uses conventional HTTP response codes to indicate the success or failure of an API request. Generally, codes in the 2xx range indicate success. Codes in the 4xx range indicate an error due to the provided information (e.g., a required parameter was missing). Codes in the 5xx range indicate an error on AltScore servers (this is rare).

Some 4xx errors that can be handled programmatically (for example, creating a duplicate entity) include an error code explaining briefly the problem.

Error Structure in the API

We constantly work to maintain error normalization in the API. If you encounter an error with a different structure, please contact us.

Description

In case of an API error, the system responds with a JSON object that includes information about the error type, a descriptive message, and additional details to help identify the problem. This error response structure allows API clients to understand the failure and take appropriate action.

Error Response Example

{
    "code": "NotFoundError",
    "message": "no results found",
    "details": {
        "id": "8cb879f3-be78-4bf1-8a48-99821546bf19"
    }
}

Fields

Field	Type	Description
`code`	string	Unique code identifying the error type (e.g., `NotFoundError`).
`message`	string	Readable message describing briefly the error (e.g., `no results found`).
`details`	object	Optional object containing additional information about the error.
`details.id`	string	Unique identifier for tracing the specific error instance.

Error Handling

It is recommended that API clients always verify the presence of a field code to determine the type of error occurred. The field message provides a useful description for the developer or end user, while details offers additional information that can be useful for support or troubleshooting issues.