Error Codes

// 400 Bad Request — may include validation details
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field \"url\": Invalid input: expected string, received undefined",
    "details": [
      {
        "expected": "string",
        "code": "invalid_type",
        "path": ["url"],
        "message": "Invalid input: expected string, received undefined"
      }
    ]
  }
}

// 401 invalid API key — no additional details
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key"
  }
}

// 401 vault reconnect required — affected provider IDs
{
  "error": {
    "code": "VAULT_RECONNECT_REQUIRED",
    "message": "1Password vault connection expired. Reconnect 1Password in Vault settings before starting a run with vault credentials.",
    "details": { "providers": ["1password"] }
  }
}

{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "X-API-Key header is required"
  }
}

curl -H "X-API-Key: ***" ...

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication failed"
  }
}

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field \"browser_profile\": Invalid option: expected one of \"lite\"|\"stealth\"",
    "details": [
      {
        "code": "invalid_value",
        "values": ["lite", "stealth"],
        "path": ["browser_profile"],
        "message": "Invalid option: expected one of \"lite\"|\"stealth\""
      }
    ]
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient credits. You have 0 credits remaining. Requested 1 runs. Add credits at https://..."
  }
}

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
    "details": {
      "status": "failed",
      "error": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
      "reason": "wallet_out_of_funds",
      "non_retryable": true,
      "balance": "-2.50",
      "currency": "usd",
      "wallet_url": "https://agent.tinyfish.ai/wallet",
      "minimum_top_up": "10.00",
      "auto_reload_needs_payment_fix": false
    }
  }
}

{
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "Wallet is not available for your account yet."
  }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Run with id 'a1b2c3d4-...' not found"
  }
}

{
  "error": {
    "code": "RETRY_REQUIRED",
    "message": "Setup session is busy. Please retry in a moment."
  }
}

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Limit: 30 requests per minute. Request a higher limit at https://agent.tinyfish.ai/credits?utm_source=api&utm_medium=rate_limit_error&utm_campaign=search",
    "details": {
      "limit": 30,
      "unit": "requests",
      "window_seconds": 60,
      "upgrade_url": "https://agent.tinyfish.ai/credits?utm_source=api&utm_medium=rate_limit_error&utm_campaign=search"
    }
  }
}

import time
import random
from tinyfish import TinyFish, RateLimitError

client = TinyFish()

def call_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError as exc:
            if attempt == max_retries - 1:
                raise
            # Prefer server hint when available
            retry_after = getattr(exc, "retry_after", None)
            wait = retry_after if retry_after else (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)

{
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Today's Big Search limit has been reached. Please try again later.",
    "details": {
      "capability": "big_search_completion",
      "limit": 5,
      "used": 5,
      "remaining": 0,
      "reason": "exhausted",
      "window": "pacific_day",
      "resets_at": "2026-09-10T07:00:00.000Z"
    }
  }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

{
  "run_id": "a1b2c3d4-...",
  "status": "FAILED",
  "result": null,
  "error": {
    "code": "SITE_BLOCKED",
    "message": "Target site blocked the automation. Try using stealth mode.",
    "category": "AGENT_FAILURE",
    "retry_after": null,
    "help_url": "https://docs.tinyfish.ai/key-concepts/browser-profiles#stealth",
    "help_message": "Getting blocked? Try enabling stealth mode."
  }
}