# 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](https://www.rfc-editor.org/rfc/rfc9457).

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:

```json
{
  "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.

```json
{
  "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.

```json
{
  "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": []
}
```