API Errors

Error Response Format

{
  "success": false,
  "message": "Error description",
  "errors": {
    "field_name": ["Specific validation error"]
  }
}

HTTP Status Codes

Code	Meaning	Common Cause
400	Bad Request	Malformed request body
401	Unauthorized	Missing or invalid token
403	Forbidden	User lacks permission for this action
404	Not Found	Resource doesn't exist
422	Validation Error	Request data failed validation rules
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error — contact support

Common Errors & Fixes

401 — Unauthorized

{ "message": "Unauthenticated." }

Fix: Include a valid Authorization: Bearer {token} header. Token may have been revoked — request a new one via /api/v1/login.

403 — Forbidden

{ "message": "You do not have the required permission." }

Fix: Your user role doesn't have permission for this action. Contact your admin to adjust your role.

422 — Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "sku": ["The sku has already been taken."]
  }
}

Fix: Check the errors object for specific field-level issues and correct your request data.

500 — Server Error

Fix: This indicates an internal issue. If persistent, contact Builda support with the request details and timestamp.