# Σφάλματα

Κάθε τελικό σημείο αποτυγχάνει με τον ίδιο τρόπο: έναν κωδικό κατάστασης HTTP και ένα περίβλημα JSON.

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

| Πεδίο | Σημασία |
|---|---|
| `type` | Ευρεία κατηγορία του σφάλματος. Από αυτό αποφασίζετε τι πρέπει να κάνετε. |
| `code` | Ακριβής αιτία, σταθερή και αναγνώσιμη από μηχανές. Κάθε κωδικός έχει παρακάτω ενότητα· το `doc_url` οδηγεί σε αυτήν. |
| `message` | Επεξήγηση αναγνώσιμη από άνθρωπο, ασφαλής για καταγραφή ή εμφάνιση σε προγραμματιστή. |
| `param` | Η παράμετρος εισόδου ή η κεφαλίδα που ευθύνεται, όταν υπάρχει. |
| `details` | Για σφάλματα εισόδου, κάθε πρόβλημα που εντοπίστηκε: `[{ "param", "message" }]`. |
| `request_id` | Το αίτημα που αφορά, όταν υπάρχει. |

Δεν χρεώνεται τίποτα για κλήση που επιστρέφει σφάλμα. Ένα αίτημα που αποτυγχάνει *αφού* γίνει αποδεκτό διατηρεί την κατάσταση
`failed`, περιέχει `error: { "type", "code", "message" }` στο αντικείμενο του αιτήματος και λαμβάνει αυτόματα επιστροφή χρημάτων.

## Τύποι

| Τύπος | Κατάσταση HTTP | Τι πρέπει να κάνετε |
|---|---|---|
| `invalid_request` | 400, 413 ή 422 | Διορθώστε το αίτημα. Η επανάληψη της ίδιας κλήσης θα αποτύχει ξανά. |
| `authentication_error` | 401 | Στείλτε έγκυρο κλειδί στο `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Χρησιμοποιήστε κλειδί με το απαιτούμενο scope. |
| `not_found` | 404 | Ελέγξτε το id του μοντέλου ή του αιτήματος. |
| `insufficient_credits` | 402 | Κάντε φόρτιση του υπολοίπου API (`top_up_url` στο σφάλμα). |
| `budget_exceeded` | 402 | Ο προσωπικός προϋπολογισμός του κλειδιού έχει εξαντληθεί. Τελική ενέργεια: ζητήστε από τον κάτοχο του κλειδιού να τον αυξήσει. |
| `conflict` | 409 | Ο πόρος δεν βρίσκεται σε κατάσταση που επιτρέπει αυτήν την κλήση. |
| `rate_limited` | 429 | Περιμένετε `Retry-After` δευτερόλεπτα και μετά επαναλάβετε. |
| `upstream_error` | 502 | Το backend του μοντέλου απέτυχε. Είναι ασφαλές να επαναλάβετε με το ίδιο `Idempotency-Key`: θα εκτελεστεί ξανά και δεν χρεωθήκατε. |
| `service_unavailable` | 503 | Το API βρίσκεται σε παύση ή μια εξάρτηση δεν είναι διαθέσιμη. Επαναλάβετε αργότερα. |
| `internal_error` | 500 | Δικό μας σφάλμα. Επαναλάβετε· αν επιμένει, επικοινωνήστε με την υποστήριξη, αναφέροντας την ώρα και το `request_id`. |

## Κωδικοί

### `invalid_request`

Γενικά κακοσχηματισμένο αίτημα (400).

### `invalid_json`

Το σώμα δεν είναι έγκυρο JSON (400).

### `invalid_body`

Το σώμα είναι έγκυρο JSON αλλά όχι αντικείμενο· η είσοδος του μοντέλου πρέπει να είναι αντικείμενο JSON (400).

### `body_too_large`

Το σώμα είναι μεγαλύτερο από 16 MB (413). Μεταφορτώστε μεγάλα αρχεία και περάστε τη URL τους αντί γι’ αυτά (δείτε [Αρχεία](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Μια παράμετρος ερωτήματος έχει λανθασμένη τιμή, για παράδειγμα `limit` εκτός του 1 έως 100, `wait` που δεν είναι αριθμός, άγνωστο
`status` ή `category`, ή `storage` διαφορετικό από `permanent` / `temporary` (400). Το `param` την κατονομάζει.

### `invalid_category`

Το `GET /openapi.json?category=` καθορίζει κατηγορία που δεν υπάρχει (400). Το `GET https://api.doitong.com/v1/categories` τις παραθέτει.

### `invalid_cursor`

Το `cursor` μιας κλήσης λίστας δεν ανήκει σε αυτήν τη λίστα (400). Ξεκινήστε ξανά χωρίς cursor.

### `invalid_idempotency_key`

Η κεφαλίδα `Idempotency-Key` είναι κενή ή μεγαλύτερη από 255 χαρακτήρες (400).

### `invalid_arguments`

Μια κλήση εργαλείου MCP περιέχει όρισμα που λείπει ή είναι κακοσχηματισμένο (μόνο MCP). Το `param` κατονομάζει το όρισμα.

### `invalid_input`

Η είσοδος του μοντέλου δεν περνά την επικύρωση (422): άγνωστη παράμετρος (το μήνυμα προτείνει την πλησιέστερη έγκυρη ονομασία),
απαιτούμενη παράμετρος που λείπει, λανθασμένος τύπος, τιμή εκτός της επιτρεπόμενης λίστας ή περιοχής, ή ταυτόχρονη παροχή της κανονικής και της
εγγενούς ονομασίας με διαφορετικές τιμές. Το `param` είναι η πρώτη προβληματική παράμετρος και το `details` παραθέτει όλες.
Δεν χρεώνεται τίποτα.

### `unsupported_file`

Ένα αρχείο έχει τύπο που δεν δεχόμαστε (422), για παράδειγμα μεταφόρτωση με μη υποστηριζόμενη επέκταση ή `content_type`
που δεν αντιστοιχεί στην επέκταση.

### `invalid_webhook_url`

Το `webhook_url` δεν είναι δημόσια URL `https://` (422). Ιδιωτικές, τοπικές και απλές διευθύνσεις `http://` απορρίπτονται.

### `missing_api_key`

Το τελικό σημείο χρειάζεται κλειδί API και δεν στάλθηκε κανένα (401).

### `invalid_api_key`

Το κλειδί είναι άγνωστο, ανακλημένο ή έχει λήξει (401).

### `insufficient_scope`

Από το κλειδί λείπει το scope που χρειάζεται αυτή η κλήση (403), για παράδειγμα `models:run` για εκτέλεση ή `models:read` για ανάγνωση
αιτημάτων και του υπολοίπου. Δείτε [Έλεγχος ταυτότητας](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Ο λογαριασμός είναι κλειστός ή σε αναστολή (403). Τα κλειδιά του δεν λειτουργούν πλέον.

### `not_found`

Η διαδρομή δεν υπάρχει (404).

### `model_not_found`

Δεν υπάρχει δημόσιο μοντέλο με αυτό το id (404). Παραθέστε τα μοντέλα με `GET https://api.doitong.com/v1/models`.

### `request_not_found`

Δεν υπάρχει αίτημα με αυτό το id στον λογαριασμό σας (404). Τα αιτήματα άλλων λογαριασμών δεν είναι ποτέ ορατά.

### `insufficient_credits`

Το **υπόλοιπο API** του λογαριασμού (πιστώσεις API, 1.000 πιστώσεις API = 1 $ — όχι οι πιστώσεις των εφαρμογών Doitong) δεν καλύπτει την
τιμή αυτής της κλήσης (402). Η απόκριση αποστέλλεται πριν χρεωθεί οτιδήποτε. Το σφάλμα περιέχει `top_up_url`· προσθέστε χρήματα
στη διεύθυνση [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) και επαναλάβετε.

```json
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

Η κλήση θα υπερέβαινε τον προσωπικό προϋπολογισμό του κλειδιού API σε πιστώσεις API (402). Ο προϋπολογισμός ορίζεται από τον κάτοχο του κλειδιού· η επανάληψη δεν βοηθά
μέχρι να τον αυξήσει.

### `conflict`

Η κλήση συγκρούεται με την τρέχουσα κατάσταση του πόρου (409).

### `idempotency_mismatch`

Το `Idempotency-Key` έχει ήδη χρησιμοποιηθεί με διαφορετικό σώμα (409). Χρησιμοποιήστε νέο κλειδί για νέα λειτουργία.

### `idempotency_in_progress`

Αυτήν τη στιγμή δημιουργείται αίτημα με το ίδιο `Idempotency-Key` (409). Επαναλάβετε σε λίγο για να το λάβετε.

### `request_active`

Το αίτημα είναι ακόμη `queued` ή `running`, επομένως δεν έχει ακόμη αρχεία για διαγραφή (409). Διαγράψτε τα αφού ολοκληρωθεί.

### `not_cancelable`

Το αίτημα είναι ήδη `succeeded` ή `failed` και δεν μπορεί να ακυρωθεί (409).

### `rate_limited`

Το κλειδί έκανε υπερβολικά πολλά αιτήματα στο τρέχον χρονικό παράθυρο (429). Δείτε τις κεφαλίδες `X-RateLimit-*` και `Retry-After`.

### `too_many_inflight`

Ο λογαριασμός έχει ήδη 10 αιτήματα `queued` ή `running` (429). Ξεκινήστε το επόμενο όταν ολοκληρωθεί ένα από αυτά.

### `upstream_error`

Το backend του μοντέλου απέρριψε ή απέτυχε να εκτελέσει το αίτημα (502 κατά την εκτέλεση ή `failed` με αυτόν τον κωδικό στο αίτημα). Οι πιστώσεις API επιστρέφονται. Αν το backend απέρριψε την είσοδο, η κλήση επιστρέφει `422 invalid_input` με το αντίστοιχο μήνυμα.

### `upstream_lost`

Το backend του μοντέλου δεν γνωρίζει πλέον το αίτημα, επομένως δεν θα φτάσει ποτέ αποτέλεσμα. Ολοκληρώνεται ως `failed` με αυτόν τον κωδικό
(τύπος `upstream_error`) και επιστρέφεται. Εκτελέστε το ξανά.

### `timeout`

Το αίτημα εκτελέστηκε περισσότερο από το όριό του (15 λεπτά για εικόνες, 60 για βίντεο, 30 για τα υπόλοιπα) και διακόπηκε. Ολοκληρώνεται ως
`failed` με αυτόν τον κωδικό και επιστρέφεται.

### `service_unavailable`

Το API βρίσκεται προσωρινά σε παύση ή μια εξάρτηση, όπως οι μεταφορτώσεις αρχείων, δεν είναι διαθέσιμη (503). Επαναλάβετε αργότερα.

### `internal_error`

Κάτι χάλασε από την πλευρά μας (500). Επαναλάβετε· αν επιμένει, επικοινωνήστε με την υποστήριξη.

### `charge_failed`

Δεν ήταν δυνατή η χρέωση του λογαριασμού λόγω εσωτερικού προβλήματος (500). Το αίτημα σημειώνεται ως `failed`· δεν αφαιρέθηκε τίποτα. Επαναλάβετε.

### `pricing_unavailable`

Η τιμή του μοντέλου δεν έχει ρυθμιστεί, επομένως δεν είναι δυνατή η προσφορά τιμής ή η εκτέλεση αυτήν τη στιγμή (500).