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.

Error	Description
Authentication headers	Organization level: `devKey` and/or `sessionId`is missing Partner level:`appKey` and/or `sessionId`is missing Spend & Expense: `apiToken` is missing
Idempotent key	The idempotent key is missing, is not in the UUID4 format, or is invalid
Request body	The specified API request body is invalid
Request parameters	Path parameters, query parameters, or body parameters are missing or invalid

401 Unauthorized

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

Error	Description
Authentication headers	Organization level: The specified `devKey` and/or `sessionId`is invalid Partner level:`appKey` and/or `sessionId`is invalid Spend & Expense: `apiToken` is invalid

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