> For the complete documentation index, see [llms.txt](https://docs.alternativepayments.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alternativepayments.io/getting-started/troubleshooting.md).

# Troubleshooting

## :x:Errors

Things don’t always go as planned. This section lists the most common errors you might encounter when using the API, what they mean, and how to resolve them. Use it as a quick reference during development and debugging.

<table><thead><tr><th width="164">HTTP Code</th><th width="219.79998779296875">Endepoint</th><th width="150.5999755859375">Typical Cause</th><th>Quick Check</th></tr></thead><tbody><tr><td><strong>400 Bad Request</strong></td><td><code>POST /payment/request</code></td><td>Missing or malformed JSON; required field omitted</td><td>Ensure body includes <code>amount</code>, <code>currency</code>, and <code>redirect_url</code> exactly as documented</td></tr><tr><td><strong>401 Unauthorized</strong></td><td>Any</td><td>Missing or expired <code>access_token</code></td><td>Call <code>POST /oauth/token</code> again and set <code>Authorization: Bearer &#x3C;token></code></td></tr><tr><td><strong>403 Forbidden</strong></td><td><code>POST /oauth/token</code></td><td>Wrong <code>client_id</code> / <code>client_secret</code> or bad Basic Auth header</td><td>Re‑encode credentials and retry</td></tr><tr><td><strong>404 Not Found</strong></td><td><code>GET /payment/ request/{id}</code></td><td>ID not present in environment</td><td>Confirm the ID and that you are using the correct base URL (sandbox vs. production)</td></tr><tr><td><strong>422 Validation Exception</strong></td><td><code>POST /payment/request</code></td><td>Business‑rule failure (e.g., unsupported currency, negative amount)</td><td>Use a valid ISO 4217 code; amount must be a positive integer</td></tr><tr><td><strong>500 Server Error</strong></td><td>Any</td><td>Unexpected internal condition</td><td>Retry with back‑off; contact support if persistent</td></tr><tr><td><strong>429 Too Many Requests</strong></td><td>Any</td><td>Rate limit exceeded (more than 5 requests per second per API key)</td><td>Slow down requests, implement retry with exponential backoff, and ensure you stay within rate limits</td></tr></tbody></table>

***

## :books:Glossary

The glossary breaks down key concepts, technical terms, and acronyms used throughout the API and dashboard. It’s a handy reference to help you stay on the same page while building your integration.

<table><thead><tr><th width="198.59991455078125">Term</th><th>Definition</th></tr></thead><tbody><tr><td><strong>access_token</strong></td><td>Bearer credential returned by <code>POST /oauth/token</code> used to authorize further requests</td></tr><tr><td><strong>amount</strong></td><td>Smallest currency unit (e.g., <code>"100"</code> = $100 USD)</td></tr><tr><td><strong>client_id / client_secret</strong></td><td>Credentials created in the dashboard; used with Basic Auth to obtain a token</td></tr><tr><td><strong>currency</strong></td><td>Three‑letter code such as <code>USD</code></td></tr><tr><td><strong>grant_type</strong></td><td>OAuth field indicating the authentication flow; always <code>client_credentials</code> here</td></tr><tr><td><strong>Payment Request</strong></td><td>Resource representing a one‑time charge and hosted checkout link</td></tr><tr><td><strong>redirect_url</strong></td><td>HTTPS location where the payer is sent after checkout</td></tr><tr><td><strong>reference_id</strong></td><td>Optional string you supply for internal correlation</td></tr><tr><td><strong>status</strong></td><td>Lifecycle stage of a Payment Request: <code>pending</code>, <code>paid</code>, <code>expired</code>, <code>cancelled</code></td></tr><tr><td><strong>token_type</strong></td><td>Value identifying the auth scheme, always <code>Bearer</code></td></tr><tr><td><strong>UUID</strong></td><td>Universally Unique Identifier used for resource IDs</td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.alternativepayments.io/getting-started/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.