---
updatedAt: 2026-05-07T16:59:42.000Z
---

Fetch the complete documentation index at: https://developer.bill.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Webhook API error responses

When you perform a BILL webhook API operation, such as Get events catalog (with `GET /v3/events/catalog`) or Create a subscription (with `POST /v3/subscriptions`), BILL sends an HTTP 200 response code for each successful request.

For error responses, BILL sends an HTTP status code depending on the error. A 4XX and 5XX error response is an array of objects. Each object includes the `timestamp`, `code`, `severity`, `category`, and `message` fields.

## 4XX client-side errors

### 400 Bad Request

BILL sends a 400 HTTP status code for a set of errors.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Error
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Authentication headers
      </td>

      <td>
        * **Organization level**: `devKey` and/or `sessionId`is missing
        * **Partner level**:`appKey` and/or `sessionId`is missing
        * **Spend & Expense**: `apiToken` is missing
      </td>
    </tr>

    <tr>
      <td>
        Idempotent key
      </td>

      <td>
        The idempotent key is missing, is not in the UUID4 format, or is invalid
      </td>
    </tr>

    <tr>
      <td>
        Request body
      </td>

      <td>
        The specified API request body is invalid
      </td>
    </tr>

    <tr>
      <td>
        Request parameters
      </td>

      <td>
        Path parameters, query parameters, or body parameters are missing or invalid
      </td>
    </tr>

    <tr>
      <td>
        Subscription limit
      </td>

      <td>
        Maximum number of subscriptions (10) reached
      </td>
    </tr>
  </tbody>
</Table>

### 401 Unauthorized

BILL sends a 401 HTTP status for an authentication header error.

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Error
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        Authentication headers
      </td>

      <td>
        * *Organization level**: The specified `devKey` and/or `sessionId`is invalid
        * *Partner level**:`appKey` and/or `sessionId`is invalid
        * *Spend & Expense**: `apiToken` is invalid
      </td>
    </tr>
  </tbody>
</Table>

### 403 Forbidden

BILL sends a 403 HTTP status for a security validation error.

| Error               | Description                                             |
| :------------------ | :------------------------------------------------------ |
| Security validation | BILL refused authorization to the specified API request |

### 404 Not Found

BILL sends a 404 HTTP status for an operation not found error.

| Error               | Description                                            |
| :------------------ | :----------------------------------------------------- |
| Operation not found | The specified endpoint in the API request is incorrect |

### 429 Too Many Requests

BILL sends a 429 HTTP status for a set of errors.

| Error          | Description                                                                                    |
| :------------- | :--------------------------------------------------------------------------------------------- |
| Idempotent key | Additional requests were made with the same idempotent key when another request is in progress |
| Rate limits    | You hit the rate limit                                                                         |

## 5XX server-side errors

### 500 Internal Server Error

BILL sends a 500 HTTP status for a set of errors. Retry the operation.

| Error                                              |
| :------------------------------------------------- |
| Generic error. Unexpected condition on the server. |

### 503 Service Unavailable

BILL sends a 503 HTTP status for a set of errors. Retry the operation.

| Error                                 |
| :------------------------------------ |
| BILL service unavailable              |
| Third-party service timeout           |
| System maintenance or system overload |