> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithsoap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The error body every /api/v1 endpoint returns, the HTTP statuses it uses, and how to handle each one.

Every Soap API error is a JSON object, except the framework's `400` below when you don't send `Accept: application/json`. Branch on the HTTP status and, where the error has one, its `code`, never on the wording: the messages are written for people and can change.

## The error body

```json theme={null}
{
  "error": "Invalid phone_number.",
  "hint": "Provide a 10-digit US phone number (with optional +1 country code)."
}
```

| Field | Present | What it is |
| - | - | - |
| `error` | Always | One sentence saying what went wrong. A validation failure names the field as a JSON pointer, for example `Validation failed: /type: enum ()` for a `type` that is neither `deposit` nor `withdrawal`. |
| `hint` | Usually | What to do about it. Log it server-side only and never show it to your customer. |
| `code` | On a `401`, a `403`, and a `400` from Soap | A stable machine-readable code: `invalid_api_key`, `invalid_json`, `source_not_allowed`, `customer_creation_disabled`, `customer_updates_disabled`, `customer_email_domain_blocked` or `customer_email_plus_address_blocked`. |

Two answers come from the web framework before Soap reads the request, so they have no `hint` or `code`: a malformed body sent with `Content-Type: application/json` is a `400`, `{"status": 400, "error": "Bad Request"}` when you send `Accept: application/json` and an HTML page otherwise, and a path the API does not serve is `{"status": 404, "error": "Not Found"}`.

## Statuses

| Status | When | Example `error` |
| - | - | - |
| `200` | Success. Every endpoint answers `200`, the ones that create something included: the API never answers `201`. | |
| `400` | The request body is not a JSON object: empty, malformed, an array or a string. `code` is `invalid_json`, except in the framework's answer above. | `Invalid JSON body.`, `Bad Request` |
| `401` | A missing, unknown or inactive API key, checked before the request body is read. `code` is `invalid_api_key`. | `API key not found.` |
| `403` | Soap refused the request for your account. On any API-key endpoint, when Soap enforces an address allowlist for your account, the request came from an address outside the server addresses your business registered with Soap (`source_not_allowed`; the key itself is valid). On [Create Customer](https://docs.paywithsoap.com/api-reference/api-v1/customers/create.md), [Update Customer](https://docs.paywithsoap.com/api-reference/api-v1/customers/update.md) and [Upsert KYC](https://docs.paywithsoap.com/api-reference/api-v1/kyc/upsert.md), Soap has blocked new customers or customer updates (`customer_creation_disabled`, `customer_updates_disabled`), or an email's domain (`customer_email_domain_blocked`), or emails with a `+` before the `@` (`customer_email_plus_address_blocked`). Nothing is created or changed. | `This API key cannot be used from this address.`, `Creating customers is disabled for this business.` |
| `404` | A path the API does not serve, or an endpoint that is switched off for your account ([KYC upsert](https://docs.paywithsoap.com/api-reference/api-v1/kyc/upsert.md), [device pings](https://docs.paywithsoap.com/api-reference/api-v1/device_pings/create.md)); the second kind has a `hint` telling you to contact Soap. | `Not Found`, `Not found` |
| `422` | Soap understood the request and refused it: a missing or invalid client secret on `POST /api/v1/device_pings`, a missing, invalid or unknown field (request bodies reject fields they don't define), an id that does not exist or belongs to another merchant (the two answers are the same), a duplicate `email`, `phone_number` or `internal_id`, or a business rule, such as both amount fields on a withdrawal, the reserved `processing_fee` sku, or a payment method your account doesn't enable. | `Customer not found.`, `Validation failed: Email has already been taken`, `Unsupported payment_options: google_pay.` |
| `500` | Something unexpected. The `hint` carries a reference id: share it with Soap. | `Something went wrong` |

Authentication failures (a missing or invalid API key or client secret) are described in [Authentication](https://docs.paywithsoap.com/api-reference/introduction.md#authentication).

> [!WARNING]
>
> Always send `Content-Type: application/json` and `Accept: application/json` with a request body. With `Accept: application/json`, the framework's `400` above comes back as JSON instead of an HTML page.

## Handling them

* **`401`:** send an active API key as `Authorization: Bearer key_...`. Retrying doesn't help.
* **`403`:** contact Soap support. Retrying doesn't help.
* **`422`:** fix the request; sending it again unchanged gets the same answer. Read `error` to find the field; each endpoint's page in the API reference lists its rules.
* **`404` for a switched-off endpoint:** ask Soap to enable it for your account. Retrying doesn't help.
* **`500`, or no answer at all:** a read (`GET`) is safe to retry. Before you retry a create, check whether the first attempt went through. Customers are unique by `email`, `phone_number` and `internal_id`, so look the customer up with [Search Customers](https://docs.paywithsoap.com/api-reference/api-v1/customers/search.md). A repeated `POST /api/v1/checkouts` makes a second checkout; the unused one expires unpaid.
* Treat the HTTP status and `code` as the machine-readable part of an error, and `error` and `hint` as text for your logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.