Skip to main content

​
Error Response Format

All API errors follow a consistent format: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}  // Optional additional context
  }
}

​
Error Codes Reference

​
MISSING_API_KEY

HTTP Status: 401 The X-API-Key header was not included in the request. 
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "X-API-Key header is required"
  }
}
Solution: Add the X-API-Key header to your request: 
curl -H "X-API-Key: $MINO_API_KEY" ...

​
INVALID_API_KEY

HTTP Status: 401 The provided API key does not exist or has been revoked. 
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  }
}
Solutions:
  1. Verify your API key is correct (no extra whitespace)
  2. Check if the key was deleted in the API Keys dashboard
  3. Generate a new key if needed

​
INVALID_INPUT

HTTP Status: 400 The request body failed validation. 
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed",
    "details": {
      "url": "Invalid URL format",
      "goal": "Required field missing"
    }
  }
}
Common Causes:
  • url is missing or not a valid URL (must include https://)
  • goal is empty or missing
  • browser_profile is not “lite” or “stealth”
  • proxy_config.country_code is not a supported 2-letter code
Solution: Check the details field for specific validation errors.

​
RATE_LIMIT_EXCEEDED

HTTP Status: 429 Too many requests in a short period. 
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}
Solutions:
  1. Implement exponential backoff in your code
  2. Space out requests (recommended: 1-2 seconds between calls)
  3. Use batch endpoints for high-volume workloads
  4. Contact support for higher rate limits
Example: Exponential Backoff 
import time
import random

def call_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)

​
UNAUTHORIZED

HTTP Status: 401 Authentication failed for a reason other than missing/invalid key. 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication failed"
  }
}
Solutions:
  1. Check your account status at mino.ai/api-keys
  2. Verify your API key hasn’t expired
  3. Try generating a new API key

​
FORBIDDEN

HTTP Status: 403 Authentication succeeded, but you lack permission for this action. 
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient credits or no active subscription"
  }
}
Common Causes:
  • No remaining credits
  • Subscription has expired
  • Attempting to access a resource you don’t own
Solution: Check your account balance and subscription status at mino.ai/api-keys.

​
NOT_FOUND

HTTP Status: 404 The requested resource does not exist. 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Run not found"
  }
}
Common Causes:
  • Invalid run_id in GET /v1/runs/:id
  • Run was deleted or never existed
  • Typo in the run ID
Solution: Verify the run ID is correct. Run IDs are returned from /v1/automation/run-async or can be listed via GET /v1/runs.

​
INTERNAL_ERROR

HTTP Status: 500 An unexpected error occurred on the server. 
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
Solutions:
  1. Retry the request after a brief delay
  2. If the error persists, check status.mino.ai for outages
  3. Contact support with your request details and timestamp

​
Run Status vs Error Codes

Error codes indicate API-level failures (authentication, validation, server errors).For automation-level failures (browser crashed, goal couldn’t be achieved), check the status and error fields in the run response. See Understanding Run Status.

​
HTTP Status Code Summary

StatusMeaningError Codes
400Bad RequestINVALID_INPUT
401UnauthorizedMISSING_API_KEY, INVALID_API_KEY, UNAUTHORIZED
403ForbiddenFORBIDDEN
404Not FoundNOT_FOUND
429Too Many RequestsRATE_LIMIT_EXCEEDED
500Server ErrorINTERNAL_ERROR

Authentication

API key setup and troubleshooting

FAQ

Common questions and issues