unauthenticated | 401 | Authenticate as 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. |
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. |
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. |