Errors — ML Junction docs

Gateway errors use a stable envelope with a sanitized public message. Internal provider details and stack traces are retained in protected logs rather than returned to clients.

{
  "error": {
    "type": "provider_error",
    "message": "The provider could not complete the request.",
    "code": "provider_execution_failed",
    "request_id": "req_...",
    "support_code": "support_...",
    "retryable": true,
    "details": {}
  }
}

Category · Meaning · Client action
validation_error · Request shape or field constraint failed · Fix the request; do not retry unchanged
authentication_error · Missing or invalid credential · Refresh or replace the credential
authorization_error · Permission or key policy denied the action · Change policy or request
rate_limit · Gateway or provider rate limit · Honor retry guidance and add backoff
timeout · Provider exceeded the time budget · Retry only when the operation is safe
provider_error · Upstream provider failure · Use retryable and fallback evidence
structured_output · Output failed required validation · Review schema and repair settings
tool_call · Tool-call generation or validation failed · Validate tool definitions and arguments
configuration_error · No route or provider configuration can satisfy the request · Inspect catalog and routing preview
conflict_error · An idempotent request is already running · Wait for the original request

Continuation recovery codes

Code · Warning or error · Client behavior
REASONING_CONTINUATION_EXPIRED · Warning; request may succeed · Continue from visible history and store the fresh token returned by the successful response
PRIOR_REASONING_NOT_REUSABLE · Warning; request may succeed · Show that prior native reasoning was not reused; visible history remains authoritative
PRIOR_REASONING_WILL_NOT_BE_RENDERED · Warning; request may succeed · Do not claim native reasoning was replayed; keep the successful fresh state if returned
tool_history.dropped · Warning; request may succeed · Inspect reason/requested/effective and correct duplicate, orphaned, or unknown tool results
PENDING_TOOL_LOOP · HTTP 409 error · Use details.missing_tool_call_ids and details.actions; do not retry unchanged
INVALID_REASONING_CONTINUATION · HTTP 400 error · Discard the malformed/tampered token and retry as a fresh history-only turn
PAYLOAD_TOO_LARGE · HTTP 413 error · Reduce continuation/native detail size or conversation payload; do not retry unchanged

async function callWithBackoff(call, maxAttempts = 3) {
  let lastError;

  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    try {
      return await call();
    } catch (error) {
      lastError = error;
      const retryable = error?.body?.error?.retryable === true;
      if (!retryable || attempt === maxAttempts) throw error;

      const delayMs = Math.min(8000, 500 * 2 ** (attempt - 1));
      await new Promise((resolve) => setTimeout(resolve, delayMs));
    }
  }

  throw lastError;
}

Canonical URL: https://mljunction.com/docs/errors