Error handling

The ListBee API uses conventional HTTP status codes and returns structured JSON error responses. Every error follows the same envelope format, making it easy for agents and code to handle failures programmatically.

Error response format

All errors return a JSON object with an error key:

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_field",
    "message": "The 'title' field is required."
  }
}

Field	Type	Description
`type`	string	Error category. Use this to decide how to handle the error.
`code`	string	Machine-readable error code. Stable across API versions.
`message`	string	Human-readable description. May change — do not match on this.

HTTP status codes

Status	Meaning	When
`200`	OK	Request succeeded
`201`	Created	Resource created successfully
`204`	No Content	Resource deleted successfully
`400`	Bad Request	Malformed JSON or invalid parameters
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Resource does not exist
`409`	Conflict	Operation conflicts with the resource's current state
`422`	Unprocessable Entity	Validation error on request body
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error — retry with backoff

Error types

Type	Description	Action
`authentication`	API key is missing, invalid, or revoked	Check your API key and retry
`invalid_request`	Request body is malformed or missing required fields	Fix the request and retry
`not_found`	The requested resource does not exist	Check the resource ID/code
`conflict`	The operation conflicts with the resource's current state	Check the resource status before retrying
`rate_limited`	Too many requests in the current window	Wait and retry after the window resets
`internal`	An unexpected error occurred on the server	Retry with exponential backoff

Common error codes

Code	Type	Description
`invalid_api_key`	authentication	The API key is not valid
`missing_required_field`	invalid_request	A required field is missing from the request
`invalid_field_value`	invalid_request	A field value is not in the expected format
`not_found`	not_found	The resource was not found
`rate_limit_exceeded`	rate_limited	Too many requests — see Rate Limits

Handling errors in code

# Python example
import httpx

resp = httpx.post(
    "https://api.listbee.so/v1/listings",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"title": "My Listing"},
)

if resp.status_code >= 400:
    error = resp.json()["error"]
    if error["type"] == "authentication":
        # Check API key
        ...
    elif error["type"] == "invalid_request":
        # Fix request parameters
        print(f"Validation error: {error['message']}")
    elif error["type"] == "rate_limited":
        # Wait and retry
        time.sleep(60)
    elif error["type"] == "internal":
        # Retry with exponential backoff
        ...
else:
    listing = resp.json()

// Node.js example
const resp = await fetch("https://api.listbee.so/v1/listings", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "My Listing" }),
});

if (!resp.ok) {
  const { error } = await resp.json();
  switch (error.type) {
    case "authentication":
      // Check API key
      break;
    case "rate_limited":
      // Wait and retry
      break;
    default:
      console.error(`API error: ${error.message}`);
  }
}