---
updatedAt: 2026-06-15T23:41:08.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Common API error codes

An API operation can fail for different reasons. If an operation fails, the server responds with an error message.

| HTTP error code | Description                                                |
| :-------------- | :--------------------------------------------------------- |
| `4XX`           | Client side unauthorized, forbidden, or bad request errors |
| `5XX`           | Server side errors                                         |

> 👍 HTTP response status codes
>
> See <Anchor label="HTTP response status codes" target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status">HTTP response status codes</Anchor> in the Mozilla developer documentation for more information about the five classes of HTTP response codes.

An error response consists of HTTP status code (e.g. `401 Unauthorized`) and additional detail fields.

| Error response field | Description                                                               |
| :------------------- | :------------------------------------------------------------------------ |
| `timestamp`          | Error response timestamp.                                                 |
| `code`               | Error code. The value begins with `BDC_`.                                 |
| `severity`           | Error severity (`ERROR`, `WARNING`, or `INFORMATION`)                     |
| `category`           | Error category (`REQUEST`, `APPLICATION`, `SERVER`, or `DOWNSTREAM`)      |
| `message`            | Error message. This message provides a short description about the error. |

```json Sample 4XX error response
[
    {
        "timestamp": "2026-12-25T00:00:00.000+00:00",
        "code": "BDC_1109",
        "severity": "ERROR",
        "category": "DOWNSTREAM",
        "message": "Session is invalid.  Please log in."
    }
]
```

## Error codes list

The BILL v2 API and v3 API relies on the same source for HTTP error response codes. You can retrieve the complete list of the error codes available in the sandbox environment with `POST /v2/Errors.json`.

```curl Retrieve error codes list
curl https://api-stage.bill.com/api/v2/Errors.json
```

There are over 500 different API error codes depending on the API operation and error type.

## Common error codes

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

      <th>
        Description & possible directions
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `"code": "BDC_1001",` `"message": "System error occurred."`

        `"code": "BDC_1002",` `"message": "Unknown error occurred."`
      </td>

      <td>
        Confirm whether a parameter is unknown or misspelt parameter in the API request. In addition, confirm whether the API request object is in the correct format.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1101",`  
        `"message": "User name and/or password do not match our records."`
      </td>

      <td>
        Confirm whether your username and password is correct. In addition, confirm whether the username and password belong to the correct environment - sandbox or production.

        Note that the BILL sandbox and production environments do not share any data.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1102",` `"message": "Developer key is invalid."`
      </td>

      <td>
        Confirm whether your developer key is correct. In addition, confirm whether the developer key belongs to the correct environment - sandbox or production.

        Note that the BILL sandbox and production environments do not share any data.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1109",`  
        `"message": "Session is invalid. Please log in."`
      </td>

      <td>
        Confirm whether your API session is valid.

        Sign in to your BILL developer account with `POST /v3/login`. In response, your API session is created and a `sessionId` is generated. Use the `sessionId` in all subsequent API calls to confirm that you are in a signed-in session.

        If your API session is inactive or idle for 35 minutes, the session expires and you are automatically signed out.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1121",` `"message": "API not supported."`
      </td>

      <td>
        If HTTP status code of the response is 404, confirm that you have the correct endpoint path without any spelling errors or capitalization errors.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1144"`
      </td>

      <td>
        Confirm whether your API requests per developer key per hour are not more than `20000`. In addition, confirm whether your `Login` API requests per developer key per hour are not more than `200`.

        When you receive this error, all subsequent API requests must wait until the beginning of the next hour. Implement exponential backoff in your code to address rate limits.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1150",`  
        `"message": "User cannot make online payments."`
      </td>

      <td>
        **Bank account setup must be complete**  
        Confirm whether your bank account setup is complete.

        See <Anchor label="Bank account setup (BILL web app)" target="_blank" href="doc:bank-account-setup">Bank account setup (BILL web app)</Anchor> for more information.

        **Paying user must have the correct user role**  
        Confirm whether the organization user making an online payment has the `Administrator` user role, `Payer` user role, or a custom user role with permissions to pay bills. Use the BILL web app to set the **Payer** user role for the organization user.

        See <Anchor label="Manage a user's role" target="_blank" href="https://help.bill.com/hc/en-us/articles/360000026286-Manage-a-user-s-role">Manage a user's role</Anchor> in the BILL Help Center for more information.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1151",`  
        `"message": "Cannot make online payments with the specified bank account."`
      </td>

      <td>
        **Bank account must be verified and active**  
        Confirm whether the added bank account is verified by BILL. In addition, confirm whether the bank account stays active and not expired.

        **Paying user must have permissions to pay with the bank account**  
        Confirm whether the organization user making an online payment has permissions to pay with bank account. Use the BILL web app to add authorized users for using the bank account.

        See <Anchor label="How to add a user to a bank account" target="_blank" href="https://help.bill.com/hc/en-us/articles/115005913906-How-to-add-nominate-a-user-to-a-bank-account">How to add a user to a bank account</Anchor> in the BILL Help Center for more information.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1155",`  
        `"message": "Payments to the country are not supported."`
      </td>

      <td>
        Confirm whether the vendor address country code is in the valid full name format. Accounting software, such as Oracle NetSuite, set the address country code as two letter or three letter country codes.
      </td>
    </tr>

    <tr>
      <td>
        `"code": "BDC_1322",`  
        `"message": "Max number of concurrent requests per organization reached."`
      </td>

      <td>
        Confirm whether your concurrent API requests per developer key per organization is not more than three.

        When you receive this error, all subsequent API requests fail until one concurrent request is completed. Implement exponential backoff in your code to address concurrent rate limits.

        See <Anchor label="API rate limits" target="_blank" href="doc:api-rate-limits">API rate limits</Anchor>  for more information.
      </td>
    </tr>

    <tr>
      <td>
        `"BDC_1361": "Untrusted session."`
      </td>

      <td>
        Confirm whether your API session is Multi-Factor Authentication (MFA)-trusted for protected API operations, such as enabling vendor auto-pay, creating a payment, or adding an organization bank account.

        See <Anchor label="MFA setup" target="_blank" href="ref:setup">MFA setup</Anchor> for more information.
      </td>
    </tr>

    <tr>
      <td>
        `"BDC_1402": "Please select a payment processing date two business days out from today."`
      </td>

      <td>
        When you add a vendor bank account, BILL requires 2 business days to complete a one-time verification of the bank account. To pay such a vendor, you must set a `processDate` that is 2 business days from the current date.

        See the <Anchor label="/v3/payments" target="_blank" href="https://developer.bill.com/reference/createpayment">/v3/payments</Anchor> API for more information.
      </td>
    </tr>
  </tbody>
</Table>