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

# Errors

> Refusal codes, what each means and what your agent does next.

Errors are JSON: `{"error":{"code","message","hint"}}`. When `hint` is present, it names your agent’s next step. `details` carries structured facts, such as `open_markets` (the country and currency pairs that are open) for a market refusal. MCP tools return the same object as an error result. Unknown paths under `/api` answer a JSON 404.

| Code | HTTP | What your agent does next |
| - | - | - |
| `unauthenticated` | 401 | Authenticate as [https://populardemand.market/auth.md](https://populardemand.market/auth.md) describes: follow the WWW-Authenticate resource\_metadata to the authorization server, get an access token with the authorization code flow and PKCE, and send it as Authorization: Bearer \<token>. A draft capability token (Authorization: CondiCapability \<token>) works only on its own draft's /api/purchases routes. |
| `grant_revoked` | 401 | Stop using this token for all Popular Demand calls. If your host holds a token issued after a newer approval, use it. Otherwise tell the person their access ended. |
| `insufficient_scope` | 403 | The person hasn’t allowed this on this connection. The permission it needs is error.details.scope (also in the WWW-Authenticate challenge). Ask them to connect again and allow it; see [https://populardemand.market/auth.md](https://populardemand.market/auth.md). |
| `forbidden` | 403 | This identity or agent grant does not allow this. Retrying unchanged will not help. |
| `origin_not_allowed` | 403 | Browser requests to this MCP endpoint are accepted only from Popular Demand's own site. Server-side MCP clients send no Origin header and are not affected. |
| `validation_error` | 400 | Check the request against the schema at [https://populardemand.market/api/openapi](https://populardemand.market/api/openapi). |
| `confirmation_required` | 400 | Ask the person, then send the call again only after their yes. |
| `market_closed` | 400 | Check error.details.open\_markets for available country/currency pairs. Ask the person before changing their destination; retrying the same closed market will not help. |
| `currency_mismatch` | 400 | Use the currency configured for the Request country; never convert or change an agreed price without the person’s confirmation. |
| `not_found` | 404 | Use a Request id from GET /api/purchases. |
| `version_conflict` | 409 | Read the current version, reconcile any change with the person, then retry with that version. |
| `request_changed` | 409 | The Request changed; this question no longer applies. Your answer was not recorded. |
| `idempotency_conflict` | 409 | This Idempotency-Key was used with different input. Resend the original input to read its result, or use a new one for a different change. |
| `draft_unavailable` | 409 | The draft was already activated, closed or has expired. Read the Request with the person’s access, or save a new one. |
| `payload_too_large` | 413 | Send a smaller body. |
| `rate_limited` | 429 | Wait until the hourly limit resets, then retry. Poll less often. |
| `invalid_state` | 409 | The record or deal does not allow this now. Read its state first. |
| `postal_code_required` | 409 | Ask the person for their delivery postal code before an Offer can be prepared. |
| `temporarily_unavailable` | 503 | Retry the same change with the same Idempotency-Key, so it is not made twice. Reads can be repeated. |


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