API Guides

Errors

Model-call failures use the error envelope of the selected protocol:

{
  "error": {
    "message": "missing api key",
    "type": "missing_api_key"
  }
}

Status Codes

HTTP statuserror.typeCauseFix
400invalid_request_errorInvalid body, empty messages, or oversized bodyFix request; do not retry
401missing_api_keyNo API keyAdd the protocol’s API key header
403invalid_api_keyKey is invalid or not ACTIVEUse a valid key
403policy_rejectedIP, model, tier, or policy is not allowedAdjust key policy
402insufficient_quotaQuota or wallet balance is insufficientTop up or adjust budget
502routing_errorNo usable model or routing failedShort backoff retry
502upstream_errorUpstream model failedShort backoff retry
503 / 504upstream_errorDependency unavailable or timed outExponential backoff retry

Debug Fields

FieldSource
X-Request-IDRequest header
model / tierRequest body
HTTP statusResponse status
error.type / error.messageError response body

Retry Check

export function shouldRetryJoyTokenError(status: number, type?: string) {
  if (status === 503 || status === 504) return true;
  if (status === 502 && (type === "routing_error" || type === "upstream_error")) return true;
  return false;
}

Do not infinitely retry 400, 401, 402, or 403. Fix the request, auth, budget, or policy first.