Error Handling

Status and Error Codes

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

VersionDateDescription
1.015 Jan 2025Original Digital Version. Aligned with PDF V1.0

The table below reflects the used HTTP status codes in case of a technical error.

HTTP Status CodeDescription
200 - OKSuccessful Request.
400 - Bad requestRequest has malformed missing or non-compliant NDJSON body or URL parameters.
401 - UnauthorisedAuthorisation header missing or invalid token.
403 - ForbiddenToken has incorrect scope or a security policy was violated.
405 - Method Not AllowedThe ASPSP tried to access the resource with a method that is not supported.
406 - Not AcceptedThe 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 RequestsToo 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 errorSomething went wrong on the API gateway or service. In this case the body might contain extra details.
503 - Service UnavailableThe service is down for maintenance. The response should include a Retry-After header indicating how long the Payer ASPSP must wait before retrying the operation.
504 - Gateway TimeoutThere was no timely response from an upstream server that was needed to complete the request.

Go directly to

Response

  • Name
    X-Request-Id
    Type
    String
    Tag(s)
    Mandatory
    Description

    A RFC4122 UUID used as a correlation id.

  • Name
    Content-Type
    Type
    String
    Tag(s)
    Mandatory
    Description

    The string ‘application/problem+json’ is used.

Body

  • Name
    type
    Type
    String
    Tag(s)
    Mandatory
    Description

    A URI reference [RFC3986] that identifies the problem type.

  • Name
    code
    Type
    String
    Tag(s)
    Mandatory
    Description

    Message code to explain the nature of the underlying error.

  • Name
    title
    Type
    String
    Tag(s)
    Description

    Short human readable description of error type. Could be in local language. To be provided by PSPs.

  • Name
    status
    Type
    String
    Tag(s)
    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)
    Description

    Detailed human readable text specific to this instance of the error.

    • Format: Max. 500 characters.
  • Name
    detail
    Type
    String
    Tag(s)
    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

    A RFC4122 UUID used as a correlation id.

  • Name
    Content-Type
    Type
    String
    Tag(s)
    Mandatory
    Description

    The string ‘application/problem+json’ is used.

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.

  • Name
    code
    Type
    String
    Tag(s)
    Mandatory
    Description

    Message code to explain the nature of the underlying error.

  • Name
    title
    Type
    String
    Tag(s)
    Description

    Short human readable description of error type. Could be in local language. To be provided by PSPs.

  • Name
    status
    Type
    String
    Tag(s)
    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)
    Description

    Detailed human readable text specific to this instance of the error.

    • Format: Max. 500 characters.
  • Name
    detail
    Type
    String
    Tag(s)
    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"}
Previous
Next