> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.yoco.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.yoco.com/_mcp/server.

The Yoco Checkout API uses standard HTTP response codes.

Codes in the `2xx` range indicate success.

Codes in the `4xx` range indicate client errors, such as missing parameters.

Codes in the `5xx` range indicate server errors.

### Common errors

| Description                          | Reason                                              | Solution                                         |
| ------------------------------------ | --------------------------------------------------- | ------------------------------------------------ |
| Cross-Origin Resource Sharing (CORS) | The request isn't sent over HTTPS from your server. | Make all API calls from your server using HTTPS. |

### HTTP response errors

| Status code | Description                                             | Reason                                                                                                  | Solution                                                                                                                                            |
| ----------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | The `expiresAt` value is outside the allowed range.     | `expiresAt` is less than 30 minutes or more than 70 days after Yoco receives the request.               | Send an `expiresAt` between 30 minutes and 70 days ahead. [See Expiring a checkout](/guides/online-payments/expiring-a-checkout).                   |
| 403         | A key is required, but hasn't been specified.           | Secret API key is missing or incorrect.                                                                 | Ensure the `Authorization` header is present and correct. [See Authentication](/docs/checkout-api/authentication).                                  |
| 404         | Checkout not found.                                     | No checkout session exists for the given ID.                                                            | Confirm the checkout ID is correct and belongs to your merchant account.                                                                            |
| 409         | Conflict                                                | A request with the same idempotency key is already being processed.                                     | Try again later or use a different idempotency key. [See Idempotency](/docs/checkout-api/idempotency).                                              |
| 409         | The checkout can't be expired.                          | A payment is in progress, the checkout's status doesn't allow expiry, or it changed during the request. | Act on the `description` in the response. [See Expire a checkout yourself](/guides/online-payments/expiring-a-checkout#expire-a-checkout-yourself). |
| 422         | The request payload doesn't match the original request. | Duplicate idempotency key with different payload.                                                       | Use a unique idempotency key for each request. [See Idempotency](/docs/checkout-api/idempotency).                                                   |
| 503         | The checkout's payment couldn't be checked.             | Yoco couldn't check the payment of a checkout you're expiring, so the checkout isn't expired.           | Try the request again. [See Expire a checkout yourself](/guides/online-payments/expiring-a-checkout#expire-a-checkout-yourself).                    |