These docs are for v1.0.0. Click to read the latest docs for v2.0.0.

Overview of error responses

OnceHub uses conventional HTTP response codes to indicate the success or failure of an API request.

Successful requests are given status codes in the 2xx range, while unsuccessful requests have status codes in the 4xx or 5xx range.

4xx codes indicate an error that failed given the information provided (e.g., an invalid parameter, object not found, etc.); 5xx codes indicate an error with OnceHub servers (these are rare).

Error structure

The API returns error responses in JSON format, with the following structure:

  "type": "invalid_request_error",
  "message": "No existing Webhook subscription with this ID can be found."

Error types

Error responses are categorized into four different types, corresponding to the following situations:

authentication_errorThe server could not authenticate your request. Check to make sure you have entered a valid API key in the correct format, in the API-Key header.
invalid_request_errorOne or more of the input parameters is not valid. Check that you have entered the correct values for all required parameters. URLs must be entered in full, and they must use the https:// prefix.
rate_limit_errorToo many requests hit the API too quickly.
api_errorThere was an error on the OnceHub servers. This type of error is rare.

Error messages

In addition to the standard HTTP codes and error type specified in the table above, each error response includes a human-readable message that provides additional details that can help you troubleshoot why the request failed.

For example, if you attempt to create a new Webhook subscription, but there is already a Webhook with the same name, you would receive the following error message:

  "type": "invalid_request_error",
  "message": "A Webhook subscription with this name already exists."