Skip to content

Error Handling

In the event of an error during REST API requests, we return error messages to help you identify and resolve issues quickly. Below is a list of common error responses and their corresponding error codes, as well as recommended actions.

If you have any issues with errors when using our REST API, please contact Keelvar Support.

HTTP 4xx Client Errors

400 (Bad Request)

The server cannot process the request due to a client error. This could be due to a missing required field or incorrect syntax. Further detail on the error(s) encountered will be included in the response body. See below for examples.

Missing Required Field

This example JSON response details a field name that is missing from the request. 

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "field_errors": {
        "name": [
            "This name is required."
        ],
        "status": [
            "This status is required."
        ]
    }
}

Incorrect Syntax

This example JSON response details a request that is incorrectly formatted or a field that contains an invalid data type. 

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errors": [
        "JSON parse error - Extra data: line 4 column 1 (char 27)"
    ]
}

Missing Field and Request Error

This example JSON response details a field name that is missing from the request with a request error message. Note: this shows how nested fields are displayed using dot notation. 

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "errors": [
        "Invalid resource ID"
    ]
    "field_errors": {
        "status": [
            "This status is required."
        ],
        "options.is_enabled": [
            "This option is required."
        ]
    }
}

Recommended actions
  • Verify that all request parameters are correctly formatted.
  • Ensure all necessary fields are provided.
  • Consult the API reference page for the correct request structure.

401 (Unauthorized)

The client must authenticate itself to get the requested response. This status code indicates that valid credentials are required to access the requested resource.

Recommended actions
  • Include your API key in the Authorization reqeust header.
  • For further details on API authentication and use of API keys, please see the Authentication page.

403 (Forbidden)

The client has provided credentials, but they are not valid to access the requested resource.

Recommended actions
  • Verify the API key you are using is correct.
  • The Authentication page has further information on how to authenticate when using the APIs.

404 (Not Found)

The server cannot locate the requested resource.

Recommended actions
  • Verify the accuracy of the requested URL and resource path.
  • Confirm that the resource exists on the server, by consulting the API reference page

429 (Too Many Requests)

The client has exceeded the rate limit or sent too many requests within a specified time frame.

Recommended actions
  • Implement proper rate limiting on the client side to avoid overloading the server.
  • Retry the request after the specified delay, as communicated on the API responses.
  • The Rate limits page has further information on the rate-limiting applied to API requests.

HTTP 5xx Server Errors

500 (Internal Server Error)

A generic error message indicating that an unexpected condition was encountered on the server.

Recommended actions

502 (Bad Gateway)

The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed.

Recommended actions
  • This is likely a transient error. Retry the request after a short delay.
  • If the issue persists, contact Keelvar Support for assistance.

503 (Service Unavailable)

The server is currently unable to handle the request due to temporary overloading or maintenance.

Recommended actions
  • This is likely a transient error. Retry the request after a short delay.
  • If the issue persists, contact Keelvar Support for assistance.