Μετάβαση στο περιεχόμενο
Χειρισμός σφαλμάτων

Χειρισμός σφαλμάτων

Ένα αίτημα που αποτυγχάνει επιστρέφει κωδικό κατάστασης 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

Επιστρέφει κατάσταση 400 και αυτό το σώμα:

400 JSON
{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: no-such-model"
  }
}

Σώμα σφάλματος

Υπάρχουν δύο σώματα. Το /v1/messages απαντά στη μορφή Anthropic· κάθε άλλο endpoint απαντά στη μορφή OpenAI. Και στις δύο, οι λεπτομέρειες βρίσκονται στα error.type και error.message, οπότε ένας αναγνώστης εξυπηρετεί όλα τα endpoints.

401 Μορφή OpenAI
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key",
    "code": "invalid_api_key",
    "param": null
  }
}
401 Μορφή Anthropic
{
  "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)

Σφάλματα μέσα σε 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 δεκαεξαδικοί χαρακτήρες όταν δεν στείλατε καμία. Καταγράψτε την και αναφέρετέ την όταν ζητάτε βοήθεια για ένα αίτημα.