# 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: 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:

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

The question should be specific, self-contained, and written in natural language.
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.