Errors - Seyaha

All error responses share the same JSON envelope:

{
  "success": 0,
  "error": ["field: reason", "another: issue"],
  "message": "Human-readable summary",
  "code": 400
}

Field	Type	Description
`success`	`0`	Always `0` for errors
`error`	`string[]`	Machine-readable list of individual error details
`message`	`string`	Short human-readable description
`code`	`number`	HTTP status code, mirrored in the body

HTTP status codes

Code	Meaning	Common causes
`400`	Bad Request	Failed Zod validation, missing required field, business rule violation
`401`	Unauthorized	Missing, expired, or invalid credential
`403`	Forbidden	Authenticated but wrong role (e.g. non-admin hitting admin route)
`404`	Not Found	Resource ID doesn’t exist or doesn’t belong to the caller
`429`	Too Many Requests	Rate limit exceeded — back off and retry
`500`	Internal Server Error	Unexpected server-side failure

Validation errors (400)

Validation uses Zod. Each failed field is a separate entry in the error array using the format fieldPath: message:

{
  "success": 0,
  "error": [
    "base_url: Invalid url",
    "auth_type: Invalid enum value. Expected 'bearer' | 'api_key'"
  ],
  "message": "Validation Error",
  "code": 400
}

Rate limiting (429)

Affiliate and Reseller endpoints are rate-limited per API token / JWT.

{
  "success": 0,
  "error": ["rate limit exceeded"],
  "message": "rate limit exceeded",
  "code": 429
}

When you hit a 429, inspect the Retry-After response header (if present) and wait that many seconds before retrying.

​HTTP status codes

​Validation errors (400)

​Rate limiting (429)

HTTP status codes

Validation errors (400)

Rate limiting (429)