Error Handling
When an application error message occurs, an HTTP status code will be returned plus an error message. The return format of the error messages are technical errors and functional errors.
Document History
| Version | Date | Description |
|---|---|---|
| 1.0 | 15 Jan 2025 | Original Digital Version. Aligned with PDF V1.0 |
| 1.1 | 27 Jan 2025 | Updated "details" within the responses to "instance", added functional errors & error table. |
| 2.0 | 20 Mar 2025 | Format changes, aligned with VoP single check API. Refer to the detailed changes here. |
Status and Error Codes
The table below reflects the used HTTP status codes in case of a technical error.
| HTTP Status Code | Description |
|---|---|
| 200 - OK | The request has succeeded. |
| 400 - Bad request | Request has malformed missing or non-compliant NDJSON body or URL parameters. |
| 401 - Unauthorised | Authorisation header missing or invalid token. |
| 403 - Forbidden | Token has incorrect scope or a security policy was violated. |
| 405 - Method Not Allowed | The Requester tried to access the resource with a method that is not supported. |
| 406 - Not Accepted | The request contained an accept header that requested a content-type other than application/x-ndjson and a character set other than UTF-8. |
| 429 - Too Many Requests | Too many requests towards the endpoint. In this case the response contains a Retry-After header indicating how long the consumer must wait before retrying the operation. |
| 500 - Internal server error | Something went wrong on the API gateway or service. In this case the body might contain extra details. |
| 503 - Service Unavailable | The service is down for maintenance. The response should include a Retry-After header indicating how long the Requesting PSP must wait before retrying the operation. |
| 504 - Gateway Timeout | There was no timely response from an upstream server that was needed to complete the request. |
Response
Header
- Name
X-Request-Id- Type
- String
- Tag(s)
- Mandatory
- Description
Value as sent in the corresponding request header.
- Name
Content-Type- Type
- String
- Tag(s)
- Mandatory
- Description
Content type and encoding of the request.
- Example: application/json
Example of Error Response Headers
| Header name | Example |
|---|---|
| X-Request-Id | 123e4567-e89b-12d3-a456-42661417400 |
| Content-Type | application/json;charset=utf-8 |
Body
- Name
type- Type
- String
- Tag(s)
- Mandatory
- Description
A URI reference [RFC3986] that identifies the problem type.
- Format: Max. 70 Characters.
- Name
code- Type
- String
- Tag(s)
- Mandatory
- Description
Message code to explain the nature of the underlying error.
- Possible Values: Refer to the list here.
- Name
title- Type
- String
- Tag(s)
- Optional
- Description
Short human readable description of error type. Could be in local language. To be provided by the Responding PSP.
- Format: Max. 70 Characters.
- Possible Values: Refer to the list here.
- Name
status- Type
- String
- Tag(s)
- Optional
- Description
HTTP response code generated by the Server. If contained, this is more relevant as the actual http response code in the actual response, because it is introduced by the Application Server.
- Name
detail- Type
- String
- Tag(s)
- Optional
- Description
Detailed human readable text specific to this instance of the error.
- Format: Max. 500 characters.
- Name
instance- Type
- String
- Tag(s)
- Optional
- Description
This attribute is containing a JSON pointer (as defined in RFC6901) or XPath expression to indicate the path to an issue generating the error in the related request.
- Format: Max. 256 characters.
Error response
[
{
"type": "https://surepay.com/problem-type/invalid-input",
"code": "FORMAT_ERROR",
"title": "Invalid input data",
"status": 400,
"detail": "Presence of two fields that are mutually exclusive",
"instance": "/request/body/field-name"
}
]
Responses within the file submitted
This section outlines errors related to individual transactions within a bulk file. While the Bulk API request may be successful overall, the response file may include errors specific to individual records (per line). The chosen structure is consistent with the error structure in the VOP specification.
File Header
- Name
X-Request-Id- Type
- String
- Tag(s)
- Mandatory
- Description
Value as sent in the corresponding request header.
- Name
Content-Type- Type
- String
- Tag(s)
- Mandatory
- Description
Content type and encoding of the request.
- Example: application/json
Example of Error Response Headers
| Header name | Example |
|---|---|
| X-Request-Id | 123e4567-e89b-12d3-a456-42661417400 |
| Content-Type | application/json;charset=utf-8 |
File Body
- Name
uetr- Type
- String
- Tag(s)
- Mandatory
- Description
The Unique End-to-End Transaction Reference (UETR) is an RFC4122 UUID used as a record-level correlation ID to uniquely track and trace individual transactions throughout the process.
- Name
type- Type
- String
- Tag(s)
- Mandatory
- Description
A URI reference [RFC3986] that identifies the problem type.
- Format: Max. 70 Characters.
- Name
code- Type
- String
- Tag(s)
- Mandatory
- Description
Message code to explain the nature of the underlying error.
- Possible Values: Refer to the list here.
- Name
title- Type
- String
- Tag(s)
- Optional
- Description
Short human readable description of error type. Could be in local language. To be provided by the Responding PSP.
- Format: Max. 70 Characters.
- Possible Values: Refer to the list here.
- Name
status- Type
- String
- Tag(s)
- Optional
- Description
HTTP response code generated by the Server. If contained, this is more relevant as the actual http response code in the actual response, because it is introduced by the Application Server.
- Name
detail- Type
- String
- Tag(s)
- Optional
- Description
Detailed human readable text specific to this instance of the error.
- Format: Max. 500 characters.
- Name
instance- Type
- String
- Tag(s)
- Optional
- Description
This attribute is containing a JSON pointer (as defined in RFC6901) or XPath expression to indicate the path to an issue generating the error in the related request.
- Format: Max. 256 characters.
Error response
{"uetr":"13b8472f-d796-436a-ba76-0be4ec234206","type":"https://surepay.com/problem-type/invalid-input","code":"FORMAT_ERROR","title":"Invalid input data","status":400,"detail":"Presence of two fields that are mutually exclusive","instance":"/request/body/field-name"}
{"uetr":"13b8472f-d796-436a-ba76-0be4ec234207","type":"https://surepay.com/problem-type/invalid-input","code":"FORMAT_ERROR","title":"Invalid input data","status":400,"detail":"Presence of two fields that are mutually exclusive","instance":"/request/body/field-name"}
Functional Errors
Error Message Codes
| HTTP Status Code | Description |
|---|---|
| FORMAT_ERROR | Incorrect data format has been provided, not compliant with the expected specifications (e.g., invalid JSON format, missing or incorrectly formatted fields). |
| CLIENT_INVALID | The client is not recognised or is invalid (,an attempt to access resources by an unauthorized client). |
| CLIENT_INCONSISTENT | The client information provided in the certificate and/or in the request message body is not consistent with related directory information |
| INTERNAL_SERVER_ERROR | An exception occurred during code execution and the request cannot be further processed. |
Error table
The following table contain a list of error code values:
| Error Message Code | HTTP Code | Title | Detailer Error |
|---|---|---|---|
| FORMAT_ERROR | 400 | INVALID_HEADER | The provided value for the header ‘___’ differs from the expected format. Possible values : X-Request-Id, Accepted-Language, Content-Type and Authorization |
| FORMAT_ERROR | 400 | MANDATORY_HEADER_NOT_PROVIDED | A mandatory header ‘___’ has not been provided, therefore the request cannot be sent. Possible values : 'X-Request-Id', 'Content-Type' and 'Authorization' |
| FORMAT_ERROR | 400 | INVALID_REQUEST | The provided JSON format in the request does not comply with the expected structure. |
| FORMAT_ERROR | 400 | MANDATORY_FIELD_NOT_PROVIDED | The request is missing the mandatory field ‘____’. Possible values : 'name' or 'identification', 'bicfi' (requesting, agent), 'iban' |
| FORMAT_ERROR | 400 | INVALID_FIELD | The provided value for the field ‘____’ differs from the expected format. Possible values : 'name', 'identification','lei', 'schemeNameCode', 'schemeNameProprietary', 'anyBIC', 'bicfi' (requesting, agent), 'issuer' |
| FORMAT_ERROR | 400 | NAME_TOO_LONG | The value provided in the field ‘name’ is longer than the maximum number of characters: 140. |
| FORMAT_ERROR | 400 | MUTUALLY_EXCLUSIVE_FIELDS_USED | Two fields mutually exclusive were added in the request. Possible values : 'name' and 'identification'; 'lei', 'anyBIC' and 'others'; 'schemeNameCode' and 'schemeNameProperty' |
| CLIENT_INVALID | 401 | The API Client has a valid certificate but is not contained in the addressed scheme directory | The Requesting’s PSP is not adherent to the Scheme. |