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:
| Field | Needed | You send |
|---|---|---|
model | yes | a text model on sale, lab/model; else a 404 |
input | yes | the whole conversation; without it, a 400 |
store | no | false, or leave it out; true gets a 400 |
previous_response_id | no | never; 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:
{
"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"
}
}| Field | Holds |
|---|---|
id | the failed response's id, resp_... |
status | failed |
error | why it failed |
code | in error: rate_limit_exceeded on a 429, server_error on every other status. It does not tell causes apart: error_type does |
message | in 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_type | the cause, in one word from the tables below, the same word the other two text routes give |
metadata | the detail, when there is some |
limit_source | in metadata, on a 402 or a 403: the limit that stopped it, wallet or key on a 402, guardrail on a 403 |
needed_micro_da | in 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_da | in metadata, on a wallet's 402, to the wallet's owner only: what the wallet holds, in µDA |
deposit_url | in 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_url | in metadata, on a key's 402: the key's page, where its cap is changed |
provider_code | in metadata, below 500: the provider's own code for the error |
The words
The request:
error_type | Status | Means |
|---|---|---|
invalid_request | 400 | a field is missing, malformed or out of range |
invalid_prompt | 400 | an item of input is not valid, such as an empty message |
context_length_exceeded | 400 | the conversation and the reply ceiling pass what the model can hold |
string_too_long | 400 | one text passes the provider's limit for a single field |
not_found | 404 | the 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_large | 413 | the body is too large |
unprocessable | 422 | the request is well formed, and impossible to carry out |
A picture in the request:
error_type | Status | Means |
|---|---|---|
invalid_image | 400 | the picture is damaged or unreadable |
image_too_large · image_too_small | 400 | the picture's file or size is past the provider's limits |
unsupported_image_format | 400 | the provider does not read this picture format |
image_download_failed | 400 | the picture's address could not be fetched |
image_not_found | 404 | the picture's address or file id leads nowhere |
The caller:
error_type | Status | Means |
|---|---|---|
authentication | 401 | the key is missing, wrong, disabled or expired |
payment_required | 402 | the balance, the key's cap or a guardrail's budget is spent |
permission_denied | 403 | the key may not do this, or a guardrail blocked it |
content_policy_violation | 403 | a filter flagged the request or the reply |
refusal | 403 | the model refused, and its provider sent the refusal as an error |
The model:
error_type | Status | Means |
|---|---|---|
timeout | 408 · 504 | the provider did not answer in time |
rate_limit_exceeded | 429 | the provider is limiting its rate |
server | 500 | an unexpected error; the message is generic |
provider_unavailable | 502 | the model is down, or answered with nothing usable |
provider_overloaded | 503 | no provider can take the request now, or meets the routing it asked for |
unmapped | any | an 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.
| Status | When |
|---|---|
| 400 | model 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 |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your 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 |
| 403 | the 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 |
| 404 | model is not a model on sale |
| 408 · 504 | the provider did not answer in time |
| 413 | the body is too large |
| 422 | an input_file part names a file that is not yours or has expired |
| 429 | the provider is limiting its rate; Retry-After says how many seconds to wait |
| 500 | an unexpected error |
| 502 | the model is down, or answered with nothing usable |
| 503 | no provider meets the routing you asked for |
Last modified on