Error Handling

All errors follow a consistent format:

Status Code: 4xx or 5xx

Response Body:

{
  "message": "Human-readable error message",
  "type": "error_type",
  "code": "ERROR_CODE"
}

Example: Authentication Error

{
  "message": "Partner authentication required",
  "type": "unauthorized",
  "code": "UNAUTHORIZED"
}

Example: Validation Error

{
  "message": "Invalid brand data: name is required",
  "type": "invalid_data",
  "code": "INVALID_DATA"
}

Example: Not Found Error

{
  "message": "Partner not found",
  "type": "not_found",
  "code": "NOT_FOUND"
}

Code	Name	Description	Example
200	OK	Request succeeded	GET resource
201	Created	Resource created successfully	POST brand
400	Bad Request	Invalid request data	Missing required field
401	Unauthorized	Authentication required or failed	Missing or invalid token
403	Forbidden	Authenticated but not authorized	Admin-only endpoint with partner token
404	Not Found	Resource doesn't exist	GET /brands/invalid_id
422	Unprocessable Entity	Validation error	Invalid email format
500	Internal Server Error	Server error	Database connection failed
503	Service Unavailable	Service temporarily down	External API timeout

Error responses follow a consistent JSON shape: a human-readable message, and where applicable a type code you can branch on programmatically.

1. Unauthorized (401)

Returned when authentication is missing or invalid.

{
  "message": "Partner authentication required",
  "type": "unauthorized"
}

2. Not Found (404)

Returned when the requested resource does not exist.

{
  "message": "Partner not found",
  "type": "not_found"
}

3. Invalid Data (400)

Returned when the request body or parameters fail validation.

{
  "message": "CustomerLabs not configured properly",
  "type": "invalid_data"
}

4. Generic Error (400)

Some endpoints return an error field with additional detail instead of a type code.

{
  "message": "Failed to create brand",
  "error": "Slug already exists"
}