Error Codes

The Simbee API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error response format

All error responses include a message field. Validation errors additionally include an errors array with field-level details.

Standard error

{
  "message": "Not found"
}

Validation error

{
  "message": "Validation failed",
  "errors": [
    { "field": "email", "message": "is required" },
    { "field": "password", "message": "is too short (minimum 8 characters)" }
  ]
}

Validation error (analytics endpoints)

Analytics endpoints (Python/FastAPI) use the OpenAPI validation format:

{
  "detail": [
    {
      "loc": ["body", "client_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

HTTP status codes

Success codes

Code	Meaning	Used for
`200`	OK	GET, PUT, PATCH, DELETE responses
`201`	Created	POST that creates a new resource
`204`	No Content	DELETE with no response body

Client error codes

Code	Meaning	Common causes
`400`	Bad Request	Malformed JSON, invalid query parameters, vector dimension mismatch
`401`	Unauthorized	Missing or expired JWT, invalid credentials on /auth/token
`403`	Forbidden	Insufficient role/scopes for the requested operation
`404`	Not Found	Resource does not exist or has been soft-deleted
`409`	Conflict	Duplicate external_id, duplicate vocabulary entry
`422`	Unprocessable Entity	Validation failed — missing required fields, invalid values
`429`	Too Many Requests	Rate limited by Envoy gateway or per-endpoint limits

Server error codes

Code	Meaning	Action
`500`	Internal Server Error	Unexpected error. Retry with backoff. If persistent, contact support.
`502`	Bad Gateway	Upstream service unavailable. Retry after a few seconds.
`503`	Service Unavailable	Service is temporarily down or overloaded. Retry with exponential backoff.

Rate limiting

The API enforces rate limits at the Envoy gateway level. When rate limited, you receive a 429 response with headers indicating the limit:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1718100000

Back off and retry after the X-RateLimit-Reset timestamp.

Retry guidance

Code	Retry?	Strategy
`400`	No	Fix the request
`401`	Yes, once	Re-authenticate, then retry with new token
`403`	No	Check your role and scopes
`404`	No	Check the resource ID
`409`	No	Resolve the conflict (duplicate ID)
`422`	No	Fix validation errors in the request body
`429`	Yes	Wait until X-RateLimit-Reset
`500`	Yes	Exponential backoff, max 3 retries
`502`	Yes	Retry after 1-2 seconds
`503`	Yes	Exponential backoff, max 5 retries