# 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 key: [Responses](/docs/reference/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:

```python
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"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    input: "Do you have this jacket in size M?",
  }),
});
const body = await response.json();

if (response.ok) {
  console.log(body.usage.cost);
} else {
  console.log(response.status, body.error_type, body.error.message);
}
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address = "https://opendunes.com/v1/responses"
	model   = "anthropic/claude-sonnet-4.5"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")

	body, err := json.Marshal(map[string]any{
		"model": model,
		"input": "Do you have this jacket in size M?",
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		ErrorType string `json:"error_type"`
		Error     struct {
			Message string `json:"message"`
		} `json:"error"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}

	if res.StatusCode == http.StatusOK {
		fmt.Println(answer.Usage.Cost)
	} else {
		fmt.Println(res.StatusCode, answer.ErrorType, answer.Error.Message)
	}
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/responses"
MODEL="anthropic/claude-sonnet-4.5"

curl "$ADDRESS" \
  -w '\n%{http_code}\n' \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "input": "Do you have this jacket in size M?"
  }'
```

## Response

The HTTP status is the error's status. Yacine's balance 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"
  }
}
```

| 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 |
| `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 deposit |
| `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 retired 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 DA 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](/docs/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 |
