Errors

Beam's APIs use a standardised format for errors (4xx and 5xx status codes).

All error bodies will contain an error_type field. This can have one of 3 values: validation, code or server.

You should assume that any endpoint can return a validation error. An endpoint can only throw a specific set of code errors (if any) and these can be seen in the example bodies in our API reference.

Validation Errors

Errors with an error_type of validation have the following format:

{
    "error_type": "validation",
    "detail": [
        {
            "type": "string_too_short",
            "loc": ["body", "first_names"],
            "msg": "String should have at least 2 characters",
            "input": "a",
            "ctx": {
                "min_length": 2
            }
        },
        {
            "type": "too_old",
            "loc": ["body", "date_of_birth"],
            "msg": "Age is too old.",
            "input": "1000-08-06"
        },
        {
            "type": "invalid_za_id",
            "loc": ["body", "gov_id"],
            "msg": "Invalid South African ID number.",
            "input": "1222222234"
        },
        {
            "type": "value_error",
            "loc": ["path", "application_id"],
            "msg": "Value error, Id must be of type PydanticObjectId",
            "input": "123",
            "ctx": {
                "error": {}
            }
        }
    ]
}

These errors are thrown when an input is invalid and generally have to do with formatting, string lengths, etc.

If loc begins with body, there is an error with the supplied json body and if it begins with path, then there is an error in the url path.

Code Errors

Errors with an error_type of code have the following format:

{
    "error_type": "code",
    "code": "no_application_configs",
    "message": "Default application config not found."
}

The code field is machine readable and corresponds with the human readable message.

Server Errors

Errors with an error_type of server always look like this:

{
    "error_type": "server",
    "message": "An error occurred."
}

When this happens, something has gone wrong on our end. We will receive a notification and start working on a fix.