Foundations

Errors & HTTP Error Codes

HTTP Status Codes for Error Responses

Rutter uses standard HTTP error codes that follow common industry practices. However, we also utilize a few custom error codes for specific conditions unique to Rutter. These custom codes are designed to offer detailed insights into the nature of the issue, accompanied by actionable error messages wherever possible.

If you are experience any of these errors and are unsure what to do, please reach out to our support team.

Actionable Error Codes

StatusSituationNotes
400Rutter will return this error when a request is made to Rutter with an invalid input. The error message should provide detailed information about the issue and suggestions. Use the information in the error message to identify and address any issues with the input data.
401Rutter will return this error when a request is made to Rutter with missing or invalid credentials. Please check that you have the correct credentials.
404Rutter will return this error when an endpoint is not implemented or is not supported for a given platform.
409Rutter will return this error when a request is made that differs from another request made with the same idempotency-key.
410Rutter will return this error when the endpoint is recognized but the requested resource is not found. This usually happens when the :id of the requested resource is invalid.We will start sending on/after January 9, 2024. Not all errors will have this response code right away. For the foreseeable future, most/many responses will still send 404 until we transition all such scenarios over to 410.
429Rutter will return this error when too many requests are being made to the Rutter service. Please allow for some time in between your requests.
450 (custom)Rutter will return this error when the underlying platform returns 400 Bad Request to differentiate from the 400 error Rutter itself returns. The error message will contain details about the problem and recommendations for resolution.We will start sending on/after January 9, 2024. Not all errors will have this response code right away. For the foreseeable future, most/many responses will still send 500 until we transition all such scenarios over to 450.
451 (custom)Rutter will return this error when the underlying platform returns an 401 Unauthorized to differentiate from the 401 error Rutter itself returns.We will start sending on/after January 9, 2024. Not all errors will have this response code right away. For the foreseeable future, most/many responses will still send 500 until we transition all such scenarios over to 451.
452 (custom)Rutter will return this error when the underlying platform returns a 429 Too Many Requests error to differentiate from the 429 error Rutter itself returns. This typically only happens for POST, PATCH, or DELETE endpoints. In such instances, we recommend leveraging the idempotent endpoint, as this enables Rutter to automatically retry the request using exponential backoff.We will start sending on/after January 9, 2024. Not all errors will have this response code right away. For the foreseeable future, most/many responses will still send 424 until we transition all such scenarios over to 452.

Server Error Codes

StatusSituationNotes
500Rutter will return this error in response to unforeseen circumstances. When this Internal Server Error happens, our team will be alerted and prioritize efforts to comprehend and address these issues promptly.
550 (custom)Rutter will return this error when the underlying platform returns 500 Internal Server Error to differentiate from the 500 error Rutter returns itself. In these situations, we will encode the platform error message in our error response. We recommend trying the request again after a delay.We will start sending on/after January 9, 2024. Not all errors will have this response code right away. For the foreseeable future, most/many responses will still send 500 until we transition all such scenarios over to 550.

Connection Errors

Errors related to a particular Connection.

Error Schema

PropertyTypeDescription
error_typestringBroad categorization of the error. Safe for programmatic use.
error_codestringThe particular error code. Safe for programmatic use.
error_messagestringA developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.

PRODUCT_NOT_READY

Returned when a data request has been made for an endpoint that is not yet ready.

PRODUCT_NOT_READY
{
 "error_type": "CONNECTION_ERROR",
 "error_code": "PRODUCT_NOT_READY",
 "error_message": "the requested product is not yet ready. please  try the request again later",
}

PRODUCT_NOT_ALLOWED

Returned when a data request has been made for an endpoint that has not been activated for your account.

PRODUCT_NOT_ALLOWED
{
 "error_type": "CONNECTION_ERROR",
 "error_code": "PRODUCT_NOT_ALLOWED",
 "error_message": "You do not have access to use this endpoint",
}

INVALID_CREDENTIALS

Returned when a data request has made with an invalid access_token or HTTP Basic Authentication credentials

INVALID_CREDENTIALS
{
 "error_type": "CONNECTION_ERROR",
 "error_code": "INVALID_CREDENTIALS",
 "error_message": "Invalid credentials to access this connection.",
}

CONNECTION_DISABLED

Returned when a request has been made for a connection that has been temporarily disabled. You may use Fetch a Connection Status to see a list of reasons why a connection is disabled and notify the merchants accordingly.

CONNECTION_DISABLED
{
 "error_type": "CONNECTION_ERROR",
 "error_code": "CONNECTION_DISABLED",
 "error_message": "This connection was disabled because of a problem. Please contact support@rutterapi.com for assistance.",
}

NEEDS_UPDATE

Returned when a request has been made for a connection that needs re-authentication.

NEEDS_UPDATE
{
 "error_type": "CONNECTION_ERROR",
 "error_code": "NEEDS_UPDATE",
 "error_message": "The merchant needs to re-authenticate this connection. Please use the update_url value to re-establish the connection.",
}

API Request Errors

MISSING_ACCESS_TOKEN

Returned when a data request has been made without access_token. To obtain access_token, please use Exchange Tokens to exchange your public_token with access_token.

MISSING_ACCESS_TOKEN
{
    "error_type": "INVALID_REQUEST",
    "error_code": "MISSING_ACCESS_TOKEN",
    "error_message": "Missing access_token in query"
}

INVALID_CURSOR

Returned when a data request has been made with a malformed pagination cursor.

INVALID_CURSOR
{
 "error_type": "INVALID_REQUEST",
 "error_code": "INVALID_CURSOR",
 "error_message": "Invalid cursor format",
}