Troubleshooting Error Messages

Learn how to troubleshoot the following HTTP status codes:

400 Bad Request

This HTTP status code indicates that an invalid request was submitted.

Checklist

Verify that the request references your customer account numberIdentifies a customer by a system-defined account number (e.g., 0001). This account number consists of alphanumeric characters. A customer's account number is displayed in the upper-right hand corner of the MCC..

Verify that your customer account is in good standing (i.e., Active status).

Verify that the Authorization header references a valid token.

Verify the request body's format matches the Content-Type header value.

Verify all characters in the request URL are URL encoded.

Verify that the request includes all required request body parameters.

Validate all request body parameters.

Verify that each request body parameter included in the request is set to a valid and properly formatted value.

Verify that required request body parameters are not set to a blank value.

More Information:

More detailed information is provided below.

Error Message Type Description

Inactive/Deleted Customer

The customer account number specified in the request URI corresponds to an inactive customer account. The response may contain a Message parameter that reports "Cannot update or retrieve information of a deleted customer."

Invalid Customer ID Value/Invalid ID Value

The customer account number specified in the request URI does not correspond to the customer account associated with the REST API token specified in the Authorization request header.

Invalid Request/Response Type

The format specified for the request body does not match the one specified in the Content-Type request header. A generic request error will be returned for this error type.

Invalid Request URL/Parameter

This type of error message occurs when the request URL or a request body parameter contains invalid or improperly formatted data. Below you will find common scenarios for this type of error message.

  • The request URL is invalid. Make sure that all characters are URL encoded. For example, space characters in a custom ID should be replaced by "%20."
  • The value assigned to a request body parameter does not match the expected format. For example, an e-mail address does not contain an @ symbol.
  • An invalid value was specified for a request body parameter. For example, a 2 was specified for a request body parameter that can only accept a value of 1 or 3.
  • A blank value was specified for a required request body parameter.
  • The value specified for a required request body parameter is of an invalid data type. For example, a letter is specified for an integer field. A generic message is returned for XML schema errors.

Missing Required Fields

This type of error message occurs when a required field for the requested endpoint was not properly specified. Below you will find common scenarios for this type of error message.

  • An empty value was specified for a required request body parameter.
  • A required request body parameter was not included in the request. A generic message is returned for XML schema errors.

401 Unauthorized

This HTTP status code indicates that an unauthorized request was submitted.

Only requests to our API gateway may return this response.

Checklist

Verify that the Authorization header references a valid token.

Verify that the token defined within the Authorization header was generated with a scope that authorizes the requested action.

More Information:

More detailed information is provided below.

Error Message Type Description

Missing/Invalid Token

Either the Authorization header was not specified or it does not comply with the following syntax:

Insufficient Permissions

The scope associated with the token is insufficient for the requested action.

Expired Token

A token automatically expires after 300 seconds (i.e., 5 minutes). Once a token has expired, it can no longer authorize requests. Generate a new token.

403 Forbidden

This HTTP status code indicates that the server refused to fulfill the request.

Checklist

Verify that the Authorization header references a valid token using the following syntax:

Verify that the specified token does not include additional characters (e.g, quotes).

Verify that the request references a valid customer account number.

Verify that your user account has sufficient privileges to perform the requested action. Specifically, your user account must be granted the HTTP methodRefers to the type of action being requested. Our REST API supports the use of the following methods: GET, POST, PUT, and DELETE. being requested and sufficient user privileges to perform the equivalent action within the TCC.

Perform a case-comparison between the request URL and the endpoint defined in the documentation.

More Information:

More detailed information is provided below.

Error Message Type Description

Authentication Failure

If a request was not authorized by the REST API service due to a missing or an invalid token value, then the response will contain a Message parameter that reports either "Invalid user" or "Access Denied." Please verify the following items:

  • The Authorization request header was included in your request.
  • The proper format was used to specify the REST API token. (i.e., TOK: Web_Service_REST_API_Token).
  • The specified token value matches the primary or backup token assigned to your account.
  • Keep in mind that the entire value specified for the Authorization header will be used to authenticate a user. Make sure that no characters other than the token header (i.e., TOK: ) and the token value have been specified. For example, enclosing the Authorization header value in quotes will generate a 403 Forbidden status code.

Insufficient Access Rights

If a request was made by a user with insufficient privileges, then the response will contain a message indicating insufficient access.

Invalid Case

This type of error message occurs when a request is formed using improper case.

404 Not Found

This HTTP status code indicates that the requested endpoint was not found.

Checklist

Compare the request URL to the endpoint defined in the documentation.

More Information:

More detailed information is provided below.

Error Message Type Description

Invalid Request URI

This type of error message occurs when the URI is requesting an endpoint that does not exist. Typically, this type of error will return an "Endpoint not found" message.

Verify the URI of the offending request. If the URI appears to be correct, make sure that a forward slash (/) has not been appended to the end of the URI.

405 Method Not Allowed

This HTTP status code indicates that the HTTP method defined in the request is not allowed.

Checklist

More Information:

More detailed information is provided below.

Error Message Type Description

Invalid Request

This type of error message typically occurs when the specified HTTP method (i.e., GET, PUT, POST, or DELETE) is not allowed for the endpoint specified by the URI. For example, performing a GET function on an endpoint that only accepts a POST will generate this message.

409 Conflict

This HTTP status code indicates that the request is trying to create a duplicate resource

Checklist

Verify that resource being created doesn't already exist.

More Information:

More detailed information is provided below.

Error Code Description

invalid_request

This type of error message typically occurs when creating a resource that already exists. For example, attempting to add a Real-Time Log Delivery after it has been configured will generate this error.

500 Internal Server Error

This HTTP status code indicates that the request could not be fulfilled by the server due to an error.

Checklist

Verify that the request URL is properly formatted.

More Information:

More detailed information is provided below.

Error Message Type Description

Server Error

This type of error message occurs when the REST API service was unable to handle the request. The response for this type of error will contain a Message parameter that reports "Method Error." Sample scenarios under which this status code will be reported are listed below.

  • The URI is not properly formatted for the requested endpoint.
  • The database is not properly responding to the request.