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.
424	FAILED_DEPENDENCY	Generic error that the request failed at dependency (institution).	Examine the message property to check what went wrong.
424	UNAUTHORISED	Credentials/SCA code passed to the dependency (institution) are invalid.	Check if correct credentials/SCA code are used.
424	RETRY_LIMIT_EXCEEDED	Retry limit for authorisation at dependency (institution) reached.	At this moment payment failed. Try to create and process a new one.
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.

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.

Error handling

Error codes and troubleshooting

Error codes

Validation errors

Validation error types

Troubleshooting

On this page