opendunes
Overview
Copy page ▾

Responses · errors

POST /v1/responses answers an error in the Responses shape: status is failed, error says why, and error_type names the cause in one word.

Request

Any request to the route, sent with an API keyAPI keyThe key you create and send with every request that calls a model.More on API keys →: Responses lists every field. Two fail on this route alone, because the route keeps nothing between requests:

FieldNeededYou send
modelyesa text model on sale, lab/model; else a 404
inputyesthe whole conversation; without it, a 400
storenofalse, or leave it out; true gets a 400
previous_response_idnonever; any value gets a 400

Souk Bot reads the word before it decides what to do:

import json
import os
import urllib.error
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/responses"
MODEL = "anthropic/claude-sonnet-4.5"

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {"model": MODEL, "input": "Do you have this jacket in size M?"}
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
try:
    with urllib.request.urlopen(request) as response:
        print(json.load(response)["usage"]["cost"])
except urllib.error.HTTPError as failure:
    body = json.load(failure)
    print(failure.code, body["error_type"], body["error"]["message"])

Response

The HTTP status is the error's status. Yacine's balanceBalanceWhat you can spend, in DA.More on Balance and charges → has run out, illustrative:

JSON
{
  "id": "resp_3e7b0d5c9a1f4e2b8c6d0a9f1e3b5c7d",
  "status": "failed",
  "error": {
    "code": "server_error",
    "message": "Insufficient balance for this request: …"
  },
  "error_type": "payment_required",
  "metadata": {
    "limit_source": "wallet",
    "needed_micro_da": 1250000,
    "available_micro_da": 400000,
    "deposit_url": "https://opendunes.com/dashboard/credit"
  }
}
FieldHolds
idthe failed response's id, resp_...
statusfailed
errorwhy it failed
codein error: rate_limit_exceeded on a 429, server_error on every other status. It does not tell causes apart: error_type does
messagein error: the reason, in words. A wallet's 402 reads Insufficient balance for this request: it needs 1.25 DA and the wallet holds 0.40 DA. Deposit at https://opendunes.com/dashboard/credit. (illustrative figures)
error_typethe cause, in one word from the tables below, the same word the other two text routes give
metadatathe detail, when there is some
limit_sourcein metadata, on a 402 or a 403: the limit that stopped it, wallet or key on a 402, guardrail on a 403
needed_micro_dain metadata, on a 402: what the request needs, in µDAµDAA millionth of a DA: 1 DA = 1 000 000 µDA.More on Balance and charges →
available_micro_dain metadata, on a wallet's 402, to the wallet's owner only: what the wallet holds, in µDA
deposit_urlin metadata, on a wallet's 402: the page where to depositDepositMoney entering your balance, by CIB or Edahabia card.More on Balance and charges →
key_urlin metadata, on a key's 402: the key's page, where its cap is changed
provider_codein metadata, below 500: the provider's own code for the error

The words

The request:

error_typeStatusMeans
invalid_request400a field is missing, malformed or out of range
invalid_prompt400an item of input is not valid, such as an empty message
context_length_exceeded400the conversation and the reply ceiling pass what the model can hold
string_too_long400one text passes the provider's limit for a single field
not_found404the model, file or job does not exist, a retiredRetiredA model withdrawn from sale. A call to its ID returns 404.More on Models → model included
payload_too_large413the body is too large
unprocessable422the request is well formed, and impossible to carry out

A picture in the request:

error_typeStatusMeans
invalid_image400the picture is damaged or unreadable
image_too_large · image_too_small400the picture's file or size is past the provider's limits
unsupported_image_format400the provider does not read this picture format
image_download_failed400the picture's address could not be fetched
image_not_found404the picture's address or file id leads nowhere

The caller:

error_typeStatusMeans
authentication401the key is missing, wrong, disabled or expired
payment_required402the balance, the key's cap or a guardrail's budget is spent
permission_denied403the key may not do this, or a guardrail blocked it
content_policy_violation403a filter flagged the request or the reply
refusal403the model refused, and its provider sent the refusal as an error

The model:

error_typeStatusMeans
timeout408 · 504the provider did not answer in time
rate_limit_exceeded429the provider is limiting its rate
server500an unexpected error; the message is generic
provider_unavailable502the model is down, or answered with nothing usable
provider_overloaded503no provider can take the request now, or meets the routing it asked for
unmappedanyan error no word above names; metadata.provider_code may carry the provider's

After the answer began. An error that comes once the model has started writing travels inside the answer, under a 200. Streamed, the last event is response.failed, its response carrying status: failed, error and usage. Not streamed, the body carries status: failed and error.

What it cost

An error before any output charges nothing: a 4xx, a 5xx, a refusal sent as an error. An error after the model began writing is charged in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges → for the tokens it produced, at the model's rates, from your balance: usage.cost in the response.failed event carries it, and GET /v1/generation shows it.

Errors

What to do on each: Errors and retries.

StatusWhen
400model or input is missing, a field has the wrong type or is out of range, store is true, previous_response_id is sent, or the provider refused a field
401the key is missing, wrong, disabled or expired
402your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; metadata.limit_source names which, and deposit_url or key_url says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries Retry-After: 60
403the key is kept to other models or other addresses, a guardrail's budget is spent, a guardrail or a filter blocked the request, or the model refused as an error
404model is not a model on sale
408 · 504the provider did not answer in time
413the body is too large
422an input_file part names a file that is not yours or has expired
429the provider is limiting its rate; Retry-After says how many seconds to wait
500an unexpected error
502the model is down, or answered with nothing usable
503no provider meets the routing you asked for

Last modified on