Documentation for errors in API requests

While the API documentation is good, it’s unfortunately lacking when it comes to errors. The OpenAI error code documentation only mentions HTTP status codes and status texts, the later of which are not available in all HTTP implementations (for example, you cannot get them with Apple’s HTTPURLResponse).

However, reading through some implementations like OpenAI’s Python implementation, errors usually seem to have a JSON body with an error object. This doesn’t seem to be documented at all. Can you please provide documentation for this? It seems to provide unambiguous and parser-friendly error codes like invalid_api_key. Is there a list of these codes available somewhere?

Normally there is an error property at the root level of the json reply. This has a sub property called message

You can get a 200 response with an error property or you can get a range of http error codes eg 404 429 and 500

1 Like

Thank you for your reply, but that’s not nearly detailed enough and doesn’t really answer my question. I want to ask OpenAI to update the official documentation about the error responses since it’s currently severely lacking.

  • What does the error object look like, e.g. which fields does it have?
  • Is the top-level error object always present when there’s an error or are there cases where just a status code is returned?
  • What are the values for the code field? It doesn’t always seem to have one.
  • If the code is missing, how can I distinguish the errors? The HTTP status codes are ambiguous, for example there’s three different errors currently documented to return a 401 status, and three errors return a 429. Remember, the status text is not always available to HTTP libraries and parsing these texts isn’t a good idea to begin with, IMHO.