Error Handling

Modaltrans uses conventional HTTP response codes to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicate success.

4xx errors indicate client-side issues where the request made by the client is incorrect or cannot be fulfilled by the server. These errors suggest that the problem lies with the client’s request, such as incorrect syntax, invalid authentication, or lack of necessary permissions.

Codes in the 5xx range indicate an error with Modaltrans’ servers.

Error Responses
When a request fails, the API returns an error response in JSON format. Depending on the type of error, the response has one of two structures.

Validation errors (422) return an errors object that lists the error messages for each field that failed validation:

{
  "errors": {
    "field_name": [
      "error_message"
    ]
  }
}

Other errors, such as 400, 403, and 404, return a single error message:

{
  "error": "error_message"
}

Some endpoints return a more detailed error structure. The error responses of each endpoint are documented on its own page. Where a translation is available, error messages are returned in the language set for your API user.

Error codes

This section provides an overview of common error codes you might encounter when using the API. For each error code listed, you'll find its probable cause and suggested solutions.

400 - Bad Request

403 - Forbidden

404 - Record Not Found

422 - Unprocessable Entity

500 - Internal Server Error

503 - Service Unavailable

Cause: The request contains a missing or invalid parameter, or its body is not valid JSON. For example, a required query parameter is not sent, or a parameter has a value that the endpoint does not accept.

Solution:

Check the error message in the response; it tells you which parameter is missing or invalid.

Ensure that all parameters and fields in the request are of the correct data types and values as specified in the API documentation.

If you need help or have any questions, please Contact our support team.

Error Handling

Error codes#

Error codes