bzzz/docs

Error Codes

All API errors return a JSON object with error (human-readable message) and code (machine-readable identifier).

json
{
  "error": "Invalid or missing authentication.",
  "code": "UNAUTHORIZED"
}

HTTP Status Codes

StatusMeaning
200Success
201Created
204Deleted (no content)
400Bad request (validation error)
401Unauthorized (missing or invalid auth)
403Forbidden (insufficient permissions)
404Not found
409Conflict (duplicate resource)
429Rate limited
500Server error

Error Codes

CodeStatusDescription
VALIDATION_ERROR400Request body failed validation. Check required fields and types.
BAD_REQUEST400Generic bad request. The error message has details.
UNAUTHORIZED401Missing Authorization header or invalid API key.
INVALID_PASSWORD400Current password is incorrect (password change).
FORBIDDEN403Your role does not have permission for this action.
NOT_FOUND404The resource (org, device, segment, member) was not found.
SLUG_TAKEN409The URL slug is already in use by another organization.
EMAIL_TAKEN409This email is already associated with an organization.
CONFLICT409Generic duplicate. For example, already subscribed to an org.
LAST_OWNER400Cannot remove the last owner from an organization.
RATE_LIMITED429Too many requests. Wait and retry.
INTERNAL_ERROR500Something went wrong on our end. Try again or contact support.

Rate Limit Response

When rate limited, the response includes:

json
{
  "error": "Too many requests. Please try again later.",
  "code": "RATE_LIMITED"
}

Current limits:

Handling Errors

javascript
const res = await fetch("https://api.bzzz.sh/v1/notify", {
  method: "POST",
  headers: {
    "Authorization": "Bearer bzzz_live_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ body: "Hello!", target: "all" }),
});

if (!res.ok) {
  const { error, code } = await res.json();
  console.error(`bzzz error [${code}]: ${error}`);
}