External Payment - Error Responses Reference

This document describes the problem types used by the External Payment API and the Payment Notifications API, following RFC 9457 – Problem Details for HTTP APIs.

Each problem type is identified by a URI in the type member of a Problem Details response. When the URI is dereferenced it should resolve to this document.

validation-error

Property	Value
Type URI	https://developer.futureordering.com/docs/external-payment-provider/error-responses#validation-error
Title	Validation Error
Status	400

The request body or query parameters failed input validation. This can mean a required field is missing, a value is out of range, or one or more business rules were violated.

Consumers should inspect the errors array in the response for per-field details:

{
  "type": "https://developer.futureordering.com/docs/external-payment-provider/error-responses#validation-error",
  "title": "Request validation failed.",
  "status": 400,
  "detail": "One or more fields failed validation.",
  "instance": "/v1/payments/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "errors": [
    {
      "code": "validation.error",
      "detail": "The field Amount must be between 1 and 9.223372036854776E+18.",
      "target": "data.amount"
    },
    {
      "code": "validation.error",
      "detail": "The field Currency must be a string with a minimum length of 3 and a maximum length of 3.",
      "target": "data.currency"
    },
    {
      "code": "validation.error",
      "detail": "The MerchantId field is required.",
      "target": "data.merchantId"
    }
  ]
}

rate-limit-exceeded

Property	Value
Type URI	https://developer.futureordering.com/docs/external-payment-provider/error-responses#rate-limit-exceeded
Title	Rate Limit Exceeded
Status	429

The client has sent too many requests in a given time window. Back off and retry in accordance with the integration guide.

{
  "type": "https://developer.futureordering.com/docs/external-payment-provider/error-responses#rate-limit-exceeded",
  "title": "Rate limit exceeded.",
  "status": 429,
  "detail": "Too many requests were sent in a given amount of time. Retry later.",
  "instance": "/v1/payments/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "errors": []
}

internal-server-error

Property	Value
Type URI	https://developer.futureordering.com/docs/external-payment-provider/error-responses#internal-server-error
Title	Internal Server Error
Status	500

An unexpected condition prevented the server from fulfilling the request. The detail member will never expose implementation internals; consult server-side logs using the instance value as a correlation identifier.

{
  "type": "https://developer.futureordering.com/docs/external-payment-provider/error-responses#internal-server-error",
  "title": "An unexpected error occurred.",
  "status": 500,
  "detail": "The server encountered an unexpected condition and could not complete the request.",
  "instance": "/v1/payments/3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "errors": []
}