Errors

The Zeeg API uses standard HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx codes indicate a client error, and 5xx codes indicate a server-side issue.

Status codes

Code	Meaning	Description
`201`	Created	The resource was created successfully.
`400`	Bad Request	The request is malformed or contains invalid parameters.
`401`	Unauthorized	Authentication is missing or invalid.
`403`	Forbidden	You do not have permission to access the resource.
`404`	Not Found	The requested resource does not exist.
`409`	Conflict	The resource already exists or conflicts with the current state.
`422`	Unprocessable Entity	The request body failed validation.
`429`	Too Many Requests	You have exceeded the rate limit. See Rate Limits.
`500`	Internal Server Error	Something went wrong on our end.

Error response shapes

The exact response shape varies slightly between endpoints. Some endpoints use an error field, while others use a success + message pattern. Always check the HTTP status code first, then parse the response body.

Returned when the request is malformed or a required parameter is missing.

{
  "success": false,
  "message": "Missing required parameter: event_uuid.",
  "status": 400
}

boolean

Always false for error responses.

string

A human-readable description of the error.

integer

The HTTP status code.

Returned when the Authorization header is missing, malformed, or the API key is invalid.

{
  "message": "Unauthenticated."
}

string

A human-readable description of the error.

Returned when the authenticated user does not have permission to access the requested resource.

{
  "success": false,
  "message": "You cannot access this resource.",
  "status": 403
}

boolean

Always false for error responses.

string

A human-readable description of the error.

integer

The HTTP status code.

Returned when the requested resource does not exist.

{
  "error": "Resource not found"
}

string

A human-readable description of the error.

Returned when the resource already exists or the request conflicts with the current state.

{
  "success": false,
  "message": "Resource already exists.",
  "status": 409
}

boolean

Always false for error responses.

string

A human-readable description of the error.

integer

The HTTP status code.

Returned when the request body fails validation. The errors object contains field-level details.

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "The field_name field is required."
    ]
  }
}

string

A summary of the validation failure.

object

A map of field names to arrays of validation error messages.

Returned when an unexpected error occurs on our side. If this persists, contact support.

{
  "success": false,
  "message": "An unexpected error occurred.",
  "status": 500
}

boolean

Always false for error responses.

string

A human-readable description of the error.

integer

The HTTP status code.

Best practices

Check the HTTP status code first. The status code is the most reliable indicator of what happened. Parse the response body only after determining the status.
Handle both error shapes. Some endpoints return {"error": "..."} while others return {"success": false, "message": "...", "status": ...}. Your client code should handle both.
Use 422 errors for form validation. The errors object gives you per-field messages you can surface directly to users.
Retry on 500 errors. Internal server errors are transient. Use exponential backoff when retrying.

Getting Started

Core Concepts

Status codes

Error response shapes

Best practices

​Status codes

​Error response shapes

​Best practices

Status codes

Error response shapes

Best practices