BBaalvion Help

Error Handling

How errors are structured, the standard error codes, and how to debug a failing request.

Error Shape

Every error response uses the same envelope as a successful response, with success: false:

Error response
{
  "success": false,
  "data": null,
  "error": {
    "code": "validation_error",
    "message": "quantity must be greater than 0",
    "field": "quantity"
  }
}

HTTP Status Codes

StatusMeaning
400Bad request — malformed input or failed validation.
401Missing or invalid credentials.
403Authenticated, but not permitted to perform this action.
404The resource doesn’t exist, or isn’t visible to your account.
429Rate limit exceeded — see Rate Limits.
500Unexpected server error. Safe to retry with backoff.

Error Codes

CodeDescription
validation_errorA field in the request body failed validation.
invalid_credentialsThe API key or token is missing, malformed, or expired.
permission_deniedThe authenticated account’s role or scope doesn’t allow this action.
not_foundThe resource ID doesn’t exist or isn’t visible to this account.
rate_limitedToo many requests — see the Retry-After header.
404 vs. 403
To avoid leaking whether a resource exists, requests for records outside your permission scope return 404 not_found rather than 403 permission_denied.

Debugging Guide

  • Check the error.field value on validation errors — it points to the exact offending field.
  • A sudden wave of 401s usually means a key was rotated or revoked — check your developer settings.
  • Confirm the account tied to your API key actually has the role required for the endpoint you’re calling.
  • For anything unclear, include the request ID from the X-Request-Id response header when contacting support.
PreviousRate LimitsNextCode Examples