Errors | OpenDunes Docs

Not yet available. The Responses API is on the roadmap. The page below documents the intended behavior.

The Responses API uses the same error envelope as the rest of OpenDunes, with a small set of additional codes for thread management.

Error Shape#

All errors return a JSON body:

JSON

{
  "error": "<code>",
  "message": "<human-readable text>",
  "retry_after": 30
}

retry_after is only present on rate_limited and temporary_unavailable responses.

Status Codes#

HTTP	`error` code	Meaning
400	`invalid_request`	Malformed JSON or missing required field
401	`unauthenticated` / `invalid_api_key`	Missing or invalid `Authorization` header
402	`insufficient_credits`	Balance too low — deposit more DA at /dashboard
403	`account_suspended` / `model_not_allowed`	Action forbidden for your account tier
404	`model_not_found`	Unknown model slug
404	`response_not_found`	The `previous_response_id` does not exist or belongs to another key
410	`response_expired`	Thread was deleted or has aged out of retention
422	(validation payload)	Invalid parameter values
429	`rate_limited`	Too many requests — back off for `retry_after` seconds
503	`temporary_unavailable`	Retry shortly
502	`upstream_error` / `upstream_timeout`	Upstream provider failed or timed out

Responses-Specific Codes#

response_not_found and response_expired are unique to the Responses API. Both mean the thread ID is no longer valid. To recover, start a new thread from the last known state on your client.

Handling Errors in Code#

Python

from openai import OpenAI
import time

client = OpenAI(
    base_url="https://opendunes.com/api/v1",
    api_key=os.environ["OPENDUNES_API_KEY"],
)

for attempt in range(3):
    try:
        response = client.responses.create(
            model="meta-llama/llama-4-maverick",
            input="Hello",
        )
        break
    except Exception as e:
        status = getattr(e, "status_code", None)
        if status == 429:
            retry_after = int(e.response.headers.get("Retry-After", 5))
            time.sleep(retry_after)
        elif status == 402:
            raise RuntimeError("Balance too low — deposit DA at opendunes.com/dashboard") from e
        else:
            raise

Mid-Stream Errors#

When streaming, an error mid-response arrives as a data event before [DONE]:

Text

data: {"error": "upstream_error", "message": "The upstream model returned an error."}

data: [DONE]

Parse every data event for an error key before treating the stream as complete.

Status Codes#

HTTP	`error` code	Meaning
400	`invalid_request`	Malformed JSON or missing required field
401	`unauthenticated` / `invalid_api_key`	Missing or invalid `Authorization` header
402	`insufficient_credits`	Balance too low — deposit more DA at /dashboard
403	`account_suspended` / `model_not_allowed`	Action forbidden for your account tier
404	`model_not_found`	Unknown model slug
404	`response_not_found`	The `previous_response_id` does not exist or belongs to another key
410	`response_expired`	Thread was deleted or has aged out of retention
422	(validation payload)	Invalid parameter values
429	`rate_limited`	Too many requests — back off for `retry_after` seconds
503	`temporary_unavailable`	Retry shortly
502	`upstream_error` / `upstream_timeout`	Upstream provider failed or timed out

Handling Errors in Code#

Python

from openai import OpenAI
import time

client = OpenAI(
    base_url="https://opendunes.com/api/v1",
    api_key=os.environ["OPENDUNES_API_KEY"],
)

for attempt in range(3):
    try:
        response = client.responses.create(
            model="meta-llama/llama-4-maverick",
            input="Hello",
        )
        break
    except Exception as e:
        status = getattr(e, "status_code", None)
        if status == 429:
            retry_after = int(e.response.headers.get("Retry-After", 5))
            time.sleep(retry_after)
        elif status == 402:
            raise RuntimeError("Balance too low — deposit DA at opendunes.com/dashboard") from e
        else:
            raise