Docs / Errors

Errors

Every error returns the same envelope so clients can rely on the shape regardless of which route produced it.

Envelope

{
  "error": {
    "code": "FETCH_RATE_LIMITED",
    "message": "Per-minute rate limit exceeded",
    "requestId": "req_01HXY...",
    "details": {
      "limit": 120,
      "window": "1m"
    }
  }
}

Always log requestId when contacting support. It ties your request to the server logs and to any request log entry in the portal.

Code reference

Code	Status	Group	Retry?	Meaning
FETCH_AUTH_REQUIRED	401	Auth	no	No API key was supplied.
FETCH_AUTH_INVALID	401	Auth	no	The key does not exist.
FETCH_AUTH_REVOKED	401	Auth	no	The key was revoked. Issue a new one.
FETCH_AUTH_EXPIRED	401	Auth	no	The key expired, or its grace period ended.
FETCH_AUTH_MALFORMED	401	Auth	no	The key is not a well-formed tfp_* key.
FETCH_PARTNER_SUSPENDED	403	Account state	no	The partner account is suspended.
FETCH_ORG_SUSPENDED	403	Account state	no	The organization is suspended.
FETCH_APP_SUSPENDED	403	Account state	no	The application this key belongs to is not active.
FETCH_ORG_CLOSED	403	Account state	no	The organization is closed.
FETCH_PAYMENT_REQUIRED	402	Account state	no	Payment is required before this call can be served.
FETCH_SCOPE_DENIED	403	Authorization	no	The key lacks the scope this route requires.
FETCH_IP_NOT_ALLOWED	403	Authorization	no	The request came from an address outside the key IP allowlist.
FETCH_RATE_LIMITED	429	Limits	yes	A rate-limit window was exceeded. See Retry-After.
FETCH_QUOTA_EXCEEDED	402	Limits	no	The plan call or unit quota is spent.
FETCH_OVERAGE_CAPPED	402	Limits	no	Usage passed the overage cap set on this application.
FETCH_INVALID_REQUEST	400	Validation	no	The request was malformed or failed validation.
FETCH_INVALID_IDEMPOTENCY_KEY	400	Validation	no	The idempotency key was reused with a different body.
FETCH_PAYLOAD_TOO_LARGE	413	Validation	no	The request body exceeded the size limit.
FETCH_NOT_FOUND	404	Lookup	no	No such resource, or it is not visible to this key.
FETCH_PROVIDER_PARTIAL	200	Upstream	yes	Some providers failed; the response holds partial results.
FETCH_PROVIDER_UNAVAILABLE	502	Upstream	yes	An upstream provider is unavailable.
FETCH_UPSTREAM_TIMEOUT	504	Upstream	yes	An upstream did not answer inside the route timeout.
FETCH_UPSTREAM_ERROR	502	Upstream	yes	An upstream returned an error.
FETCH_INTERNAL_ERROR	500	Server	yes	Something failed on our side. The requestId identifies it.
FETCH_SERVICE_DEGRADED	503	Server	yes	The service is degraded and shedding load.
FETCH_CIRCUIT_OPEN	503	Server	yes	The circuit breaker for this upstream is open.
FETCH_SANDBOX_ONLY	403	Sandbox	no	This operation is available in sandbox only.
FETCH_GONE	410	Deprecation	no	This endpoint was removed. See the changelog.

Envelope

{ "error": { "code": "FETCH_RATE_LIMITED", "message": "Per-minute rate limit exceeded", "requestId": "req_01HXY...", "details": { "limit": 120, "window": "1m" } } }

Always log requestId when contacting support. It ties your request to the server logs and to any request log entry in the portal.

Code reference

Code	Status	Group	Retry?	Meaning
FETCH_AUTH_REQUIRED	401	Auth	no	No API key was supplied.
FETCH_AUTH_INVALID	401	Auth	no	The key does not exist.
FETCH_AUTH_REVOKED	401	Auth	no	The key was revoked. Issue a new one.
FETCH_AUTH_EXPIRED	401	Auth	no	The key expired, or its grace period ended.
FETCH_AUTH_MALFORMED	401	Auth	no	The key is not a well-formed tfp_* key.
FETCH_PARTNER_SUSPENDED	403	Account state	no	The partner account is suspended.
FETCH_ORG_SUSPENDED	403	Account state	no	The organization is suspended.
FETCH_APP_SUSPENDED	403	Account state	no	The application this key belongs to is not active.
FETCH_ORG_CLOSED	403	Account state	no	The organization is closed.
FETCH_PAYMENT_REQUIRED	402	Account state	no	Payment is required before this call can be served.
FETCH_SCOPE_DENIED	403	Authorization	no	The key lacks the scope this route requires.
FETCH_IP_NOT_ALLOWED	403	Authorization	no	The request came from an address outside the key IP allowlist.
FETCH_RATE_LIMITED	429	Limits	yes	A rate-limit window was exceeded. See Retry-After.
FETCH_QUOTA_EXCEEDED	402	Limits	no	The plan call or unit quota is spent.
FETCH_OVERAGE_CAPPED	402	Limits	no	Usage passed the overage cap set on this application.
FETCH_INVALID_REQUEST	400	Validation	no	The request was malformed or failed validation.
FETCH_INVALID_IDEMPOTENCY_KEY	400	Validation	no	The idempotency key was reused with a different body.
FETCH_PAYLOAD_TOO_LARGE	413	Validation	no	The request body exceeded the size limit.
FETCH_NOT_FOUND	404	Lookup	no	No such resource, or it is not visible to this key.
FETCH_PROVIDER_PARTIAL	200	Upstream	yes	Some providers failed; the response holds partial results.
FETCH_PROVIDER_UNAVAILABLE	502	Upstream	yes	An upstream provider is unavailable.
FETCH_UPSTREAM_TIMEOUT	504	Upstream	yes	An upstream did not answer inside the route timeout.
FETCH_UPSTREAM_ERROR	502	Upstream	yes	An upstream returned an error.
FETCH_INTERNAL_ERROR	500	Server	yes	Something failed on our side. The requestId identifies it.
FETCH_SERVICE_DEGRADED	503	Server	yes	The service is degraded and shedding load.
FETCH_CIRCUIT_OPEN	503	Server	yes	The circuit breaker for this upstream is open.
FETCH_SANDBOX_ONLY	403	Sandbox	no	This operation is available in sandbox only.
FETCH_GONE	410	Deprecation	no	This endpoint was removed. See the changelog.