Skip to main content

​
Error schema

All error responses share a common JSON structure:
​
code
string
required
Machine-readable error code identifying the error type.
​
message
string
required
Human-readable description of the error.
​
details
object | null
Optional additional context. May include field-level validation errors or other structured data.

​
HTTP status codes

​
400 Bad Request

The request body is invalid, missing required fields, or fails validation. 
{
  "code": "validation_error",
  "message": "name is required",
  "details": {
    "field": "name"
  }
}

​
401 Unauthorized

The request is missing credentials, or the provided token or API key is expired, revoked, or malformed. 
{
  "code": "unauthorized",
  "message": "token is expired or invalid",
  "details": null
}

​
403 Forbidden

Credentials are valid but the caller lacks the required permission. Also returned when the organization’s monthly evaluation quota is exceeded, or when the target environment is not enabled in the current region. 
{
  "code": "forbidden",
  "message": "insufficient permissions",
  "details": null
}

​
404 Not Found

The requested resource does not exist, or the caller does not have visibility into it. 
{
  "code": "not_found",
  "message": "Flag not found",
  "details": null
}

​
409 Conflict

The request conflicts with the current state of the server. Common causes:
  • A resource with the same unique key or email already exists
  • Attempting to delete a role that is currently assigned to one or more members
  • Attempting to delete the last organization in your account
  • Attempting to resend a verification email when the email is already verified
  • Attempting to open a billing portal when the organization has no Stripe customer record
{
  "code": "conflict",
  "message": "email already exists",
  "details": null
}

​
500 Internal Server Error

An unexpected server-side error occurred. Most commonly surfaced when a billing provider (Stripe) call fails during checkout or portal session creation. 
{
  "code": "internal_error",
  "message": "billing provider returned an unexpected error",
  "details": null
}

Build docs developers (and LLMs) love

Get started for freeTalk to us