Errors

When the RouteCloud API generates an error, it returns a meaningful HTTP Status Code and a structured Error Response that may contain a list of Validation Errors.

HTTP Status Codes

The RouteCloud API aims to return standard and meaningful http status codes for all requests. Successful requests respond with 2xx or 3xx status codes, while all errors respond with 4xx or 5xx status codes. Additionally, all 4xx errors (and some 5xx errors) return an error_response detailing the issue more precisely.

The HTTP status codes that the RouteCloud API can return are listed below.

Successful Status Codes (2xx, 3xx)

These return a response body specific to the request.

200 OK - The request was completed successfully.
302 Redirect - Redirect to the location specified in the Location header.

Request Error Codes (4xx)

These always return a error_response in the response body. Reading the response body assists diagnosis of the issue.

400 Bad Request - Validation errors. The error_response includes a list of validation_errors.
401 Unauthorized - The resource requires authentication and authorization.
404 Not Found - The resource does not exist.
405 Method Not Allowed - The http method is incorrect. For example, you have performed a GET request where only POST is allowed.
409 Conflict - The path is valid, but the resource does not currently exist. For example, the task is still running, or has been canceled.
415 Unsupported Media Type - The Content-Type request header is not valid. The Content-Type should typically be application/json.
429 Too Many Requests - The request concurrency limit of 10 has been reached. Wait for some of the queued requests to complete before submitting more.

Server Error Codes (5xx)

These may return an error_response in the response body, and always indicate a server-side error.

500 Internal Server Error - An error occurred on the Verizon Connect RouteCloud server.
5xx - All other 5xx errors indicate an issue on a Verizon Connect server.

Error Responses

error_response

For all 4xx status codes, and some 5xx errors, the RouteCloud API returns an error_response object.

Name	Type	Description
error_code	error_code	A more specific error code than the http status code.
errors	validation_error[]	An array of validation errors. This is only supplied with an `error_code` of `validation_failed_error`.
message	string	A message containing details of what happened.
status_code	integer	The http status code that was returned in the http header.

For example, providing an invalid task_id GET https://routecloud.telogis.com/v1/tasks/task_id_invalid/result:

{
  "status_code": 404,
  "error_code": "invalid_task_id_error",
  "message": "The task_id 'task_id_invalid' does not exist."
}

Or sending POST https://routecloud.telogis.com/v1/sequence?wait=1 with a body of { "routes": [{ "jobs": [{}] }] }:

{
  "status_code": 400,
  "error_code": "validation_failed_error",
  "message": "Validation failed with 1 error.",
  "errors": [
    {
      "property": "request.jobs[0].location",
      "code": "job_location_missing_error",
      "message": "A job must specify a 'location'.",
      "parameters": {
        "property_name": "location"
      }
    }
  ],
  "extra_error_information": {
    "validation_failures_count": 1
  }
}

error_code

The RouteCloud API returns the following error codes in an error_response. Note that some status_codes are used in multiple error_codes, so it is preferable to check the error_code when diagnosing 4xx errors.

`error_code`	`status_code`	Description
`validation_failed_error`	400	The request body has a validation fault. The `errors` field is included, and contains one or more `validation_errors`.
`too_many_jobs_to_insert_error`	400	insert operation error. Too many jobs to insert.
`authentication_required_error`	401	No authentication mechanism was provided, and one of the methods described in Authentication must be provided.
`invalid_session_id_error`	401	A session ID was provided but was invalid.
`invalid_basic_auth_error`	401	The Authorization header was provided, but its contents were invalid.
`not_found_error`	404	The path does not exist.
`invalid_task_id_error`	404	The path was valid, but the provided `task_id` was invalid.
`method_not_allowed_error`	405	The http method, such as using `GET` instead of `POST`, was invalid for this resource.
`task_not_complete_error`	409	The task has not completed, so the result is not yet available, but should be soon.
`task_canceled_error`	409	The task was canceled.
`unsupported_media_type_error`	415	The request body had an incorrect Content-Type header. The Content-Type should typically be `application/json` for `POST` requests.
`internal_server_error`	500	The request failed unexpectedly. Try again later, and contact Verizon Connect if the issue persists.
`geostream_error`	500	Unable to geocode or reverse_geocode a single address, as an error was encountered. Try again later, and contact Verizon Connect if the issue persists.
`geostream_exceeded_maximum_retries`	500	Unable to geocode or reverse_geocode a single address, as too many repeated errors were encountered. Try again later, and contact Verizon Connect if the issue persists.
`geostream_unavailable`	500	Unable to process a geocode or reverse_geocode request, as the upstream Geostream server is unavailable. Try again later, and contact Verizon Connect if the issue persists.

Validation Errors

An array of validation_errors are returned in the errors property of an error_response when the error_response.error_code has a value of "validation_error". The array lists issues in the request body about the structure of the provided JSON, and/or any constraints that were not met.

validation_error

Name	Type	Description
attempted_value	value	For some codes, gives the value that was provided where the error occurred.
code	validation_error_code	The code of this validation failure.
line	integer	For some codes, gives the line number where the error occurred.
message	string	A message containing details of the validation failure.
position	integer	For some codes, gives the position in the line where the error occurred.
status_code	string	The http status code that was returned in the http header.

For example:

{
  "status_code": 400,
  "error_code": "validation_failed_error",
  "message": "Validation failed with 3 errors.",
  "errors": [
    {
      "property": "request",
      "code": "route_dates_mismatch_error",
      "message": "If any routes have a 'date' specified then all routes must have a 'date'."
    },
    {
      "property": "request",
      "code": "routes_with_schedules_must_have_dates_error",
      "message": "If any schedules are defined, then all routes must have a 'date'."
    },
    {
      "property": "request.job",
      "code": "null_value_error",
      "message": "'job' must not be null."
    }
  ]
}