Error Codes

Get3W uses two levels of error reporting:

• HTTP errors — returned as the HTTP status code with a JSON body when the request itself fails (authentication, validation, insufficient balance, etc.)
• Task errors — returned inside the task result object when the task was accepted but failed during execution

HTTP Error Response Format

HTTP errors from /v1/ endpoints return code plus error:

{
  "code": 401,
  "error": "Invalid or revoked API key"
}

Field	Type	Description
code	int	HTTP status code (matches the response status)
error	string | object	Error description, or a nested error object

WARNING

error is usually a string, but for some errors — an unrecognized provider in the slug, and insufficient balance — it is a nested object carrying its own code and error. The outer code is always the HTTP status; the inner code is the business error code:

{
  "code": 400,
  "error": {
    "code": 1401,
    "error": "Invalid provider: 'notaprovider'. Please check the model slug format: {provider_id}/{model_id}/{run_type}"
  }
}

Parse defensively — check whether error is a string or an object before reading it.

Chat endpoints are the exception: POST /v1/chat/completions and GET /v1/models return the OpenAI error shape instead, so an OpenAI client can consume them unchanged:

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "model"
  }
}

Authentication failures on chat endpoints still use the {"code","error"} shape above, because they are rejected before the handler runs.

HTTP Status Codes

Code	Name	Description
200	OK	Request successful
400	Bad Request	Invalid parameters or request body
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient balance for the estimated cost
403	Forbidden	Account suspended, or prompt blocked by content policy
404	Not Found	Endpoint or model slug does not exist
500	Internal Server Error	Unexpected server-side error

Get3W does not enforce per-minute rate limits or concurrency caps, so there is no 429. See What are Account Tiers.

400 — Bad Request

Returned when request validation fails.

Error	Cause
Invalid parameters	Missing required fields or wrong types

401 — Unauthorized

Returned when authentication fails.

Error	Cause
Missing Authorization header	No Authorization header in the request
Invalid Authorization format, expected: Bearer <api_key>	Header is not in Bearer <key> format
Invalid or revoked API key	Key does not exist or has been deleted

402 — Payment Required

Error	Cause
Insufficient balance. Current: $X.XXX, required: $X.XXX. Please top up and try again.	Account balance is lower than the estimated cost of the task

404 — Not Found

Error	Cause
Not found	The requested endpoint or resource does not exist

500 — Internal Server Error

Error	Cause
Server error	An unexpected error occurred on the server

Task Error Codes

When a task is accepted (HTTP 200) but fails during execution, the task result includes a code and error field:

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "model": "google/nano-banana-pro/text-to-image",
  "status": "failed",
  "code": 1200,
  "outputs": [],
  "error": "Content moderation: prompt contains prohibited content",
  "created_at": "2026-03-28T07:50:42"
}

Code	Name	Description
0	Success	Task completed successfully
1200	Content Moderation	Prompt or input was flagged by content moderation
1201	Real Person Detected	Input image contains a real person; use illustrations or AI-generated characters instead
1202	Copyright Violation	The output may be related to copyright restrictions; avoid copyrighted characters, brands, or content
1400	Missing Parameter	A required parameter was not provided
1401	Invalid Parameter	A parameter value is invalid or out of range
1402	Media Access Failed	Could not download or access the provided media URL
1403	Task Execution Failed	The task encountered an error during processing
1405	Task Failed	General task failure
5000	Internal Error	An internal system error occurred
5003	Service Unavailable	The upstream model provider is temporarily unavailable
5004	Timeout	The task timed out waiting for a response from the provider

Retry Strategy

For transient errors (HTTP 500 and task codes 5000, 5003, 5004), implement exponential backoff:

import time
import requests

def api_request_with_retry(url, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json_data)

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 500:
            wait_time = 2 ** attempt
            time.sleep(wait_time)
        else:
            response.raise_for_status()

    raise Exception("Max retries exceeded")

For task-level transient errors, retry by submitting a new task.

Next Steps

• Get Started with API — Make your first API call
• API Authentication — Authentication details and account tiers