Χειρισμός σφαλμάτων
Ένα αίτημα που αποτυγχάνει επιστρέφει κωδικό κατάστασης HTTP και σώμα JSON με τύπο σφάλματος και μήνυμα. Αυτή η σελίδα απαριθμεί κάθε κατάσταση, δείχνει το σώμα σφάλματος κάθε μορφής API και λέει ποια σφάλματα αξίζει να σταλούν ξανά.
Τα SDKs ρίχνουν ένα αντικείμενο σφάλματος που φέρει τον κωδικό κατάστασης και τα πεδία του σώματος. Αυτό το αίτημα ονομάζει ένα μοντέλο που δεν υπάρχει:
import openai
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.shannon-ai.com/v1",
)
try:
client.chat.completions.create(
model="no-such-model",
messages=[{"role": "user", "content": "Hello"}],
)
except openai.APIStatusError as error:
print(error.status_code) # 400
print(error.type) # invalid_request_error
print(error.body["message"]) # unknown model: no-such-model
print(error.response.headers.get("x-request-id")) # the id of this request import OpenAI from "openai";
const client = new OpenAI({
apiKey: "YOUR_API_KEY",
baseURL: "https://api.shannon-ai.com/v1",
});
try {
await client.chat.completions.create({
model: "no-such-model",
messages: [{ role: "user", content: "Hello" }],
});
} catch (error) {
if (!(error instanceof OpenAI.APIError)) throw error;
console.log(error.status); // 400
console.log(error.type); // invalid_request_error
console.log(error.error.message); // unknown model: no-such-model
} curl -i https://api.shannon-ai.com/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "no-such-model",
"messages": [{"role": "user", "content": "Hello"}]
}' Επιστρέφει κατάσταση 400 και αυτό το σώμα:
{
"error": {
"type": "invalid_request_error",
"message": "unknown model: no-such-model"
}
} Σώμα σφάλματος
Υπάρχουν δύο σώματα. Το /v1/messages απαντά στη μορφή Anthropic· κάθε άλλο endpoint απαντά στη μορφή OpenAI. Και στις δύο, οι λεπτομέρειες βρίσκονται στα error.type και error.message, οπότε ένας αναγνώστης εξυπηρετεί όλα τα endpoints.
{
"error": {
"type": "authentication_error",
"message": "Invalid API key",
"code": "invalid_api_key",
"param": null
}
} {
"type": "error",
"error": {
"type": "authentication_error",
"message": "Invalid API key"
}
} | Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
error.type | string | Το είδος του σφάλματος. Δείτε παρακάτω Τύποι σφαλμάτων. |
error.message | string | Μια πρόταση για άνθρωπο. Τα κείμενα στους παρακάτω πίνακες είναι σταθερά ως προς τα μεταβλητά τους μέρη, που εμφανίζονται ως <id>, <n> ή …. |
error.code | string | null | Υπάρχει σε ορισμένα σφάλματα της μορφής OpenAI: invalid_api_key με 401, request_too_large με 413, context_length_exceeded όταν μια συνομιλία είναι πολύ μεγάλη, αλλιώς null ή απουσιάζει. Αποφασίστε πρώτα με βάση την κατάσταση και το error.type και θεωρήστε το code επιπλέον πληροφορία. |
error.param | null | Υπάρχει στα ίδια σφάλματα με το code. Πάντα null. |
type | string | Μόνο στη μορφή Anthropic. Πάντα error. |
Τύποι σφαλμάτων
| Τύπος | Καταστάσεις | Περιγραφή |
|---|---|---|
invalid_request_error | 400, 413, 415, 422 | Το ίδιο το αίτημα είναι λάθος: ένα πεδίο, το σώμα, το id μοντέλου ή μια είσοδος που το μοντέλο δεν δέχεται. Αλλάξτε το αίτημα πριν το στείλετε ξανά. |
authentication_error | 401 | Το κλειδί API λείπει, είναι άγνωστο ή ανακλήθηκε. |
not_found_error | 404 | Η διαδρομή δεν υπάρχει. |
rate_limit_error | 429 | Το υπόλοιπο δεν καλύπτει το αίτημα, η προστασία από υπερφόρτωση το σταμάτησε ή το μοντέλο είναι απασχολημένο. Το μήνυμα λέει ποιο από τα τρία. |
api_error | 500, 502, 503, 504 | Το αίτημα ήταν σωστό και η αποτυχία είναι από τη δική μας πλευρά. Στείλτε το ξανά. |
server_error | 500 | Το αίτημα ήταν σωστό και η αποτυχία είναι από τη δική μας πλευρά. Στείλτε το ξανά. |
Κωδικοί κατάστασης
| Κατάσταση | Τύπος | Μήνυμα | Πότε |
|---|---|---|---|
400 | invalid_request_error | Failed to parse the request body as JSON: … | Το σώμα δεν είναι έγκυρο JSON. |
400 | invalid_request_error | unknown model: <id> | Το model δεν είναι δημοσιευμένο id. Στο /v1/responses συμβαίνει επίσης όταν λείπει το model. |
400 | invalid_request_error | No user message provided | Επίπεδα Shannon: το αίτημα δεν περιέχει κείμενο χρήστη. |
400 | invalid_request_error | <id> does not accept image input | Στάλθηκε εικόνα σε φιλοξενούμενο μοντέλο ανοιχτών βαρών χωρίς είσοδο εικόνας. |
400 | invalid_request_error | audio and video input are not supported by any hosted model | Στάλθηκε μέρος ήχου ή βίντεο σε φιλοξενούμενο μοντέλο ανοιχτών βαρών. |
400 | invalid_request_error | <id> does not accept response_format | Ζητήθηκε δομημένη έξοδος από φιλοξενούμενο μοντέλο ανοιχτών βαρών που δεν την υποστηρίζει. |
400 | invalid_request_error | <id> does not accept response_format json_schema; use json_object | Στάλθηκε JSON schema σε φιλοξενούμενο μοντέλο ανοιχτών βαρών που δέχεται μόνο json_object. |
400 | invalid_request_error | unknown reasoning effort '<value>'; expected off, low, medium or high | Η προσπάθεια συλλογισμού δεν είναι μία από τις αναγραφόμενες τιμές. Φιλοξενούμενα μοντέλα ανοιχτών βαρών. |
400 | invalid_request_error | count_tokens is available for the hosted open models; unknown model: <id> | Ζητήθηκε μέτρηση tokens για μοντέλο εκτός των φιλοξενούμενων μοντέλων ανοιχτών βαρών. |
401 | authentication_error | Missing authentication | Δεν στάλθηκε κλειδί API. |
401 | authentication_error | Invalid API key | Το κλειδί είναι άγνωστο, αντικαταστάθηκε από νεότερο ή ανακλήθηκε. |
404 | not_found_error | Not Found | Η διαδρομή δεν υπάρχει, για παράδειγμα /v1/embeddings. |
405 | api_error | Method Not Allowed | Η διαδρομή υπάρχει αλλά όχι με αυτή τη μέθοδο HTTP. |
413 | invalid_request_error | Failed to buffer the request body: … | Το σώμα του αιτήματος είναι μεγαλύτερο από 32 MiB. |
415 | invalid_request_error | Expected request with `Content-Type: application/json` | Η κεφαλίδα Content-Type λείπει ή δεν είναι application/json. |
422 | invalid_request_error | Failed to deserialize the JSON body into the target type: … | Λείπει ένα υποχρεωτικό πεδίο, όπως το messages, ή ένα πεδίο έχει λάθος τύπο JSON. |
429 | rate_limit_error | Quota exceeded. Upgrade your plan at shannon-ai.com/plan | Το όριο εξόδου του αιτήματος είναι μεγαλύτερο από όσο απομένει στο υπόλοιπό σας. |
429 | rate_limit_error | Too many requests. Retry in <n>s. | Προστασία από υπερφόρτωση: περισσότερα από 120 αιτήματα σε ένα λεπτό στον λογαριασμό σας. Το <n> είναι ο αριθμός δευτερολέπτων μέχρι να τελειώσει το λεπτό. |
429 | rate_limit_error | Shannon Coder call quota reached. Upgrade your plan at shannon-ai.com/plan | shannon-coder-1 στα /v1/chat/completions και /v1/messages: οι κλήσεις Shannon Coder του πλάνου σας για το τρέχον παράθυρο των 4 ωρών έχουν εξαντληθεί. |
429 | rate_limit_error | Shannon routes are temporarily busy. Please retry. | Το μοντέλο είναι απασχολημένο αυτή τη στιγμή. |
500 | server_error | The model backend failed to answer. Please retry. | Το μοντέλο δεν παρήγαγε απάντηση. |
500 | server_error | An internal error occurred. Please retry. | Εσωτερική αποτυχία κατά την προετοιμασία του αιτήματος. |
502 | api_error | The model backend failed to answer. Please retry. | Το μοντέλο δεν παρήγαγε απάντηση. Οικογένεια Shannon 3 και φιλοξενούμενα μοντέλα ανοιχτών βαρών. |
503 | api_error | Could not verify your quota right now. Please retry. | Το υπόλοιπό σας δεν μπόρεσε να διαβαστεί αυτή τη στιγμή. |
503 | api_error | token counting is temporarily unavailable for this model | Η μέτρηση tokens δεν είναι διαθέσιμη για αυτό το μοντέλο αυτή τη στιγμή. |
504 | api_error | upstream timed out | Ένα φιλοξενούμενο μοντέλο ανοιχτών βαρών χρειάστηκε περισσότερο από το χρονικό όριο ενός αιτήματος χωρίς streaming. |
Οι έλεγχοι εκτελούνται με αυτή τη σειρά: κλειδί API, σώμα αιτήματος, id μοντέλου, προστασία από υπερφόρτωση, υπόλοιπο. Ένα αίτημα με λάθος κλειδί και λάθος σώμα επιστρέφει επομένως 401. Ένα αίτημα που απορρίπτεται με κατάσταση 4xx δεν χρεώνεται.
Υπόλοιπο και προστασία από υπερφόρτωση
Κάθε αίτημα εξυπηρετείται εξίσου: δεν υπάρχουν επίπεδα ρυθμού ούτε ξεχωριστή ποσόστωση API. Δύο πράγματα μπορούν ακόμη να απαντήσουν 429, και τα δύο με τον τύπο rate_limit_error. Το μήνυμα τα ξεχωρίζει.
Υπόλοιπο
Το υπόλοιπό σας είναι το σημερινό ημερήσιο όριο του πλάνου, που μηδενίζεται στις 00:00 UTC, και μετά από αυτό το αγορασμένο credit. Το chat και το API αντλούν από το ίδιο υπόλοιπο.
Κάθε αίτημα δεσμεύει πρώτα το όριο εξόδου του: max_tokens, ή max_output_tokens στο /v1/responses, 4,096 όταν δεν στείλετε κανένα. Όταν ολοκληρωθεί η απάντηση, το δεσμευμένο ποσό αντικαθίσταται από όσο χρησιμοποίησε το αίτημα. Αν το ποσό δεν χωρά στο υπόλοιπο που απομένει, το αίτημα επιστρέφει Quota exceeded πριν ξεκινήσει το μοντέλο.
Τα αιτήματα που εκτελούνται ταυτόχρονα δεσμεύουν το καθένα το δικό του ποσό. Πολλά παράλληλα αιτήματα με υψηλό max_tokens μπορούν επομένως να εξαντλήσουν το υπόλοιπο για λίγο, ακόμη κι όταν κάθε απάντηση είναι σύντομη. Ένα χαμηλότερο max_tokens δεσμεύει λιγότερο.
Προστασία από υπερφόρτωση
Η προστασία από υπερφόρτωση επιτρέπει 120 αιτήματα ανά λεπτό ανά λογαριασμό. Μετρά τον λογαριασμό, όχι το κλειδί, στα /v1/chat/completions, /v1/responses και /v1/messages μαζί. Το λεπτό αρχίζει με το πρώτο σας αίτημα.
Το αίτημα με αριθμό 121 μέσα σε εκείνο το λεπτό επιστρέφει Too many requests. Retry in <n>s. και δεν κοστίζει τίποτα. Μετρούν και τα αιτήματα που απορρίπτονται, οπότε ένας client που ξαναστέλνει χωρίς να περιμένει συνεχίζει να απορρίπτεται μέχρι να τελειώσει το λεπτό. Περιμένετε τα <n> δευτερόλεπτα του μηνύματος.
Τα αιτήματα που στέλνονται παράλληλα δεν απορρίπτονται επειδή είναι παράλληλα. Περιμένουν σε ουρά και απαντώνται με τη σειρά.
Το GET /v1/models και τα endpoints μέτρησης tokens δεν προσμετρώνται.
Περισσότερα για τα όρια και το υπόλοιπο, και πού να δείτε το δικό σας υπόλοιπο και τη χρήση: Όρια και υπόλοιπο Κλειδιά & χρήση
Τι να δοκιμάσετε ξανά
Στείλτε ξανά ένα αίτημα μόνο όταν το ίδιο αίτημα μπορεί να πετύχει. Τα SDKs του OpenAI και της Anthropic δοκιμάζουν ήδη μόνα τους δύο φορές τις απαντήσεις 429 και 5xx· ορίστε το max_retries (maxRetries στη JavaScript) για να το αλλάξετε.
| Σφάλμα | Να σταλεί ξανά; | Πώς |
|---|---|---|
400, 404, 405, 413, 415, 422 | Όχι. Διορθώστε πρώτα το αίτημα. | Το μήνυμα ονομάζει το πεδίο, το μοντέλο ή την είσοδο που είναι λάθος. |
401 | Όχι. Χρησιμοποιήστε έγκυρο κλειδί. | Δημιουργήστε ή αντικαταστήστε το κλειδί στη σελίδα Κλειδιά & χρήση. |
429 Too many requests | Ναι, μετά την αναμονή. | Περιμένετε τον αριθμό δευτερολέπτων του μηνύματος και μετά στείλτε το ίδιο αίτημα. |
429 Quota exceeded | Όχι ως έχει. | Χαμηλώστε το max_tokens, περιμένετε την ημερήσια επαναφορά στις 00:00 UTC ή προσθέστε credit. |
429 Shannon Coder call quota reached | Ναι, στο επόμενο παράθυρο. | Τα παράθυρα ξεκινούν κάθε 4 ώρες από τις 00:00 UTC. Ένα άλλο μοντέλο απαντά αμέσως. |
429 … temporarily busy | Ναι. | Περιμένετε λίγα δευτερόλεπτα και μετά περισσότερο σε κάθε επόμενη προσπάθεια. |
500, 502, 503 | Ναι. | Περιμένετε 1 δευτερόλεπτο, μετά 2, 4 και 8. Σταματήστε μετά από λίγες προσπάθειες και αναφέρετε το id του αιτήματος. |
504 | Ναι. | Στείλτε το με το stream ορισμένο σε true: το χρονικό όριο ισχύει για απαντήσεις χωρίς streaming. |
Ένας βρόχος επανάληψης που ακολουθεί αυτόν τον πίνακα:
import re
import time
import openai
from openai import OpenAI
# max_retries=0: this loop does the retrying, the SDK does not add its own.
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1", max_retries=0)
def create_with_retry(attempts=5, **request):
for attempt in range(attempts):
try:
return client.chat.completions.create(**request)
except openai.RateLimitError as error:
text = str(error)
flood = re.search(r"Retry in (\d+)s", text)
if flood:
time.sleep(int(flood.group(1))) # flood protection: wait out the minute
elif "temporarily busy" in text:
time.sleep(2 ** attempt)
else:
raise # balance: a wait of seconds does not help
except (openai.InternalServerError, openai.APIConnectionError):
time.sleep(2 ** attempt) # 1, 2, 4, 8 seconds
raise RuntimeError("the request failed after all attempts")
response = create_with_retry(
model="shannon-3",
messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content) import OpenAI from "openai";
// maxRetries: 0 — this loop does the retrying, the SDK does not add its own.
const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1", maxRetries: 0 });
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));
async function createWithRetry(request, attempts = 5) {
for (let attempt = 0; attempt < attempts; attempt++) {
try {
return await client.chat.completions.create(request);
} catch (error) {
const text = String(error.message);
const flood = text.match(/Retry in (\d+)s/);
if (error.status === 429 && flood) {
await sleep(Number(flood[1])); // flood protection: wait out the minute
} else if (error.status === 429 && text.includes("temporarily busy")) {
await sleep(2 ** attempt);
} else if (error.status >= 500 || error instanceof OpenAI.APIConnectionError) {
await sleep(2 ** attempt); // 1, 2, 4, 8 seconds
} else {
throw error; // wrong request, wrong key or balance
}
}
}
throw new Error("the request failed after all attempts");
}
const response = await createWithRetry({
model: "shannon-3",
messages: [{ role: "user", content: "Hello" }],
});
console.log(response.choices[0].message.content); Σφάλματα μέσα σε stream
Ένα stream έχει κατάσταση 200 από το πρώτο byte. Μια αποτυχία μετά από αυτό φτάνει ως συμβάν μέσα στο stream: ένα chunk με μέλος error στο /v1/chat/completions, ένα συμβάν error στο /v1/messages, ένα συμβάν response.failed ή error στο /v1/responses. Τα συμβάντα κλεισίματος του stream ακολουθούν παρ' όλα αυτά. Θεωρήστε μια τέτοια απάντηση αποτυχημένη και στείλτε ξανά το αίτημα, όπως για κατάσταση 5xx.
Μια συνομιλία μεγαλύτερη από το παράθυρο συμφραζομένων του μοντέλου αναφέρεται με αυτόν τον τρόπο, με τον τύπο invalid_request_error και τον κωδικό context_length_exceeded. Συντομεύστε τη συνομιλία πριν την ξαναστείλετε.
Τα ακριβή frames περιγράφονται στο streaming. Ροή
Ids αιτημάτων
Κάθε απάντηση, και τα σφάλματα, έχει κεφαλίδα x-request-id. Είναι η τιμή που στείλατε στη δική σας κεφαλίδα x-request-id ή 12 δεκαεξαδικοί χαρακτήρες όταν δεν στείλατε καμία. Καταγράψτε την και αναφέρετέ την όταν ζητάτε βοήθεια για ένα αίτημα.