Home › Payment processing › How API works › Error handling

Error codes and troubleshooting

Understanding error responses is crucial for effective integration and debugging. This section outlines the possible error codes, their meanings, and tips for resolution.

{
  "code": "BAD_REQUEST",
  "message": "Missing \"X-Volt-Initiation-Channel\" HTTP header."
}
Field Description
code A string that provides more detailed information about what happened and why the request failed. Refer to the Error Codes section for possible values.
message A human-readable message that describes the problem. This message is not language-dependent and is always provided in English.

Error codes

HTTP Status Error code Description How to resolve
400 BAD_REQUEST Generic error that request could not be handled. Examine the message property to check what went wrong.
400 MISSING_HTTP_HEADER Required HTTP header is missing. Examine the message property and add the missing HTTP header.
400 INVALID_HTTP_HEADER HTTP header contains an invalid value. Check the documentation for valid HTTP header values.
400 MALFORMED_PATH_PARAM Path parameter has an invalid value/format. Can occur when the ID sent in the path is not a valid UUID. Examine the message property to check what went wrong.
400 MISSING_QUERY_PARAM Required query parameter is missing. Examine the message property and add the missing query parameter.
400 INVALID_QUERY_PARAM Query parameter contains an invalid value. Check the documentation for valid query parameter values.
400 MALFORMED_QUERY_PARAM Query parameter has an invalid value/format. Examine the message property to check what went wrong.
400 CONFIGURATION_ERROR Partner’s configuration is invalid and does not allow processing the request. Examine the message property to check what went wrong.
401 UNAUTHORISED Invalid credentials were used. Check if correct credentials for the API are used.
403 ACCESS_DENIED Access to perform the operation with the given resource is denied. Ensure you have access to the given resource.
404 RESOURCE_NOT_FOUND Requested resource does not exist. Ensure you are trying to operate on an existing resource.
405 METHOD_NOT_SUPPORTED HTTP method is not supported for this URL. Fix either the HTTP method used or the URL.
406 MEDIA_TYPE_NOT_ACCEPTABLE API is not able to generate a response in the format defined in the Accept HTTP request header. Use a supported format.
409 CONFLICT Generic error that the request could not be handled due to an invalid state, and would conflict with an existing resource. Try the request with different parameters.
409 IDEMPOTENCY_CONFLICT Idempotency key (from X-Volt-Idempotency-Key) has already been used. Generate a unique idempotency key for each request.
409 RESOURCE_NOT_MODIFIABLE Resource cannot be modified due to an invalid state or unexpected change request. Try the request with different parameters.
410 GONE Requested resource does not exist and will never exist. Ensure you are trying to operate on an existing resource.
415 UNSUPPORTED_MEDIA_TYPE Request contains data in an unsupported content type. Send the request with a supported media/content type.
422 VALIDATION_FAILURE Input data validation failed. Examine the errors property to check what went wrong and which data needs to be fixed.
429 RATE_LIMIT_EXCEEDED Too many requests were sent in a given timeframe. Slow down your request frequency.
500 INTERNAL_SERVER_ERROR Request could not be processed due to a server error. Contact support. The message will contain a trace ID and timestamp, allowing investigation of what went wrong.

In very rare circumstances, where our API has encountered something unexpected, you may receive an UNKNOWN error code.  If this is a recurring issue, please let us know at support@volt.io.

Validation errors

When input data constraints are violated, the API responds with a 422 Unprocessable Entity status code and provides detailed information about the validation errors.

{
  "code": "VALIDATION_FAILURE",
  "message": "Input data validation failed.",
  "errors": [
    {
      "type": "TOO_SHORT",
      "propertyPath": "payment.amount",
      "message": "The amount must be at least 100."
    },
    {
      "type": "INVALID_FORMAT",
      "propertyPath": "payer.email",
      "message": "The email address is not in a valid format."
    }
  ]
}
Field Data type Description
code string Indicates the type of error (VALIDATION_FAILURE in this case).
message string

A general message about the validation failure.
errors array of objects Each object represents a specific validation error.
errors.[].type string Categorizes the type of validation error. Refer to the Validation Error Types section for possible values.
errors.[].propertyPath string Points to the specific field or property in the incoming request that violated the validation rule.
errors.[].message string A human-readable message describing the validation error. Always in English.

Validation error types

Validation errors are categorised to provide clear insights into what went wrong and how to resolve the issue. Below is a comprehensive list of validation error types supported by the Volt API.

Error type Description
TOO_FEW Too few elements were provided.
TOO_MANY Too many elements were provided.
TOO_LOW Value (numeric) is too low.
TOO_HIGH Value (numeric) is too high.
TOO_SHORT Value (string) is too short.
TOO_LONG Value (string) is too long.
NOT_EQUAL Value is not equal to the given constraint (and should be).
IS_EQUAL Value is equal to the given constraint (and should not be).
INVALID_FORMAT Value is in an invalid format.
INVALID_DATE Value is an invalid date.
INVALID_TIME Value is an invalid time.
INVALID_TYPE Value is not of the expected type.
REGEX_FAILED Regular expression failed against the given value.
OUT_OF_RANGE Value is out of range (numeric range, available choices, etc.).
CHECKSUM_FAILED Checksum is invalid.
NOT_UNIQUE Value is not unique.
VALUE_REQUIRED Value is required (and should not be null).
INVALID_VALUE General information that the value is invalid. Appears if the validation error cannot be assigned to any other type.
MISSING_FIELD Field/property is required.
FIELD_NOT_ALLOWED Field/property is not allowed to be present in the request.

Troubleshooting

In the event you receive a 5xx Server Error response from the Volt API, the error message will include a unique TraceId and Timestamp.
TraceId serves as an identifier for the specific request. It is invaluable for our support team when diagnosing and resolving issues. 

Important Notes:

  • Do not retry: Repeating the request is unlikely to succeed and may cause additional issues.
  • Contact support: Email support@volt.io with the TraceId  and any relevant details.
  • Secure information: Ensure no sensitive data is included when sharing error information.
← Previous Payment status flow
Next → Notifications (webhooks)