Error handling

We use conventional HTTP status codes to indicate the success or failure of an API request. In general:

• Codes in the `2xx` range indicate success.
• Codes in the `4xx` range indicate a client-side error (e.g., a required parameter was omitted, invalid data was sent, etc.).
• Codes in the `5xx` range indicate an error with our servers (these are rare), in case of doubt you can visit our status page.

When an API request fails (returns a `4xx` or `5xx` status code), the response body will contain a JSON object detailing the error.

Error response structure

All error responses follow a consistent JSON format:

{
  "error": {
    "message": "A human-readable description of the error.",
    "details": "Optional: Additional details or structured information about the error."
  }
}

HTTP status codes

Here are some common HTTP status codes you might encounter:

Common error messages

While the specific `message` and `details` will vary, here are examples associated with common status codes:

`400` Bad Request:

• "message": "Invalid request", "details": "Missing required field: \url`"`
• "message": "Invalid request", "details": "Invalid \Webhook ID` format."`
• "message": "Invalid request body"

`401` Unauthorized:

• "message": "Invalid API key", "details": "The provided API key is invalid or does not exist"
• "message": "Missing API key", "details": "API key is required for authentication"
• "message": "Authentication required"

`404` Not Found:

• "message": "Webhook not found", "details": "Webhook with ID \wh_...` does not exist or does not belong to this organization."`
• "message": "Resource not found"

`409` Conflict:

• "message": "Conflict", "details": "A webhook with this URL already exists for your organization."

`429` Too Many Requests:

• "message": "Rate limit exceeded"

`500` Internal Server Error:

• "message": "Internal server error"
• "message": "Database error", "details": "Failed to execute database query."

Handling errors

Your integration should gracefully handle potential API errors:

1. Check the HTTP Status Code: Determine the general outcome of the request.
2. Parse the Response Body: If the status code indicates an error (`4xx` or `5xx`), parse the JSON response body.
3. Use Error Information: Use the `message` and `details` from the parsed JSON to understand the specific problem.
4. Implement Logic: Based on the error type, implement appropriate logic (e.g., prompt the user to fix input for a `400` error, check credentials for `401`, retry later for `429` or `5xx` errors).
5. Log Errors: Log errors, including the full response body and potentially the request ID (if provided in headers), to aid debugging.