Error Codes

All errors — from validation to payment to upstream failures — use one envelope:

{
  "error": {
    "code": "provider_timeout",
    "message": "Provider \"dexscreener\" did not respond in time.",
    "provider": "dexscreener"
  },
  "requestId": "9f2c…"
}

• error.code — stable machine-readable code from the table below.
• error.message — human/agent-readable explanation.
• error.provider — present only on provider-scoped errors; names the upstream that failed.
• error.details — optional structured context (e.g. issues for validation).
• requestId — matches the X-Request-Id header and server logs.

Codes

Code	HTTP	Meaning
validation_error	400	The JSON body is missing, malformed, or fails the service’s input schema. details.issues lists field-level problems (path, message). Web-context schemas are strict: unknown keys are rejected.
unsupported_options	400	The request asked for an upstream mode that would exceed the one-cent cost envelope (e.g. Exa deep/summary modes, Firecrawl enhanced or JSON extraction). The option is refused rather than silently downgraded — see Pricing & Guardrails.
not_found	404	Unknown route or unknown service slug. The message points to GET /services and GET /openapi.json for discovery.
payment_required	402	Payment is enforced and the request carried no valid payment. The response includes the PAYMENT-REQUIRED header with signed-payment terms; retry with PAYMENT-SIGNATURE.
payment_not_configured	402	This deployment is not currently accepting payments, so the paid route cannot be served. The boundary fails closed — paid content is never served for free.
provider_unconfigured	503	A required upstream source is not available on this deployment; the service is unavailable until it is. The message names the source.
provider_error	502	An upstream provider returned an unexpected failure. error.provider names it.
provider_timeout	504	An upstream provider did not respond in time.
provider_rate_limited	429	An upstream provider rate-limited the server. Back off and retry.
no_data	404	The request was valid but no data exists — e.g. a token with no DEX pairs, or an unknown protocol slug with no fallback hit.
internal_error	500	Unexpected server error. Report the requestId.

Validation error example

{
  "error": {
    "code": "validation_error",
    "message": "Invalid input. See details for field-level issues.",
    "details": {
      "issues": [
        {
          "path": "tokenAddress",
          "message": "Expected a 0x-prefixed 40-hex-character EVM address"
        }
      ]
    }
  },
  "requestId": "…"
}

Retry guidance for agents

Status	Action
400	Fix the input using details.issues; do not retry unchanged.
402	Sign a payment and retry.
404	Re-discover via GET /services; for no_data, treat as a definitive empty answer.
429 / 502 / 504	Retry with backoff.
503	The service is unavailable on this deployment — retrying won’t help; treat it as down.
500	Retry once; then report with the requestId.