Errors

Zentake returns standard HTTP status codes. Error response bodies are thin, a single detail message, not a rich structured error object with error codes or per-field validation arrays. The spec documents most error responses as just a description string rather than a full object schema; the one endpoint in the spec with explicit example bodies (POST /v2/webhooks/events/test) confirms the shape is:

{
  "detail": "<human-readable message>"
}

Treat detail as a human-readable string for logs and debugging, not as a stable machine-parseable error code, the spec doesn't define an enum of error codes.

400 Bad Request

Returned for validation failures and malformed input. The exact detail message varies by endpoint, the spec shows several different messages for this status:

{
  "detail": "Validation error."
}

{
  "detail": "Invalid file type. Only CSV files are allowed."
}

{
  "detail": "Webhook config ID is required."
}

401 Unauthorized

Returned when X-API-KEY and/or X-API-SECRET are missing from the request. This is the one message the spec uses consistently everywhere:

{
  "detail": "No credentials provided."
}

403 Forbidden

Returned when X-API-KEY / X-API-SECRET are present but don't match a valid credential pair (including using sandbox credentials against production, or vice versa). Also consistent across the spec:

{
  "detail": "Invalid credentials."
}

404 Not Found

Returned when the requested resource doesn't exist (or doesn't belong to your team). The detail message names the resource type, for example:

{
  "detail": "Message not found."
}

{
  "detail": "Webhook config not found."
}

Other resources follow the same "<Resource> not found." pattern, patients, forms, documents, packets, and responses each return their own message naming the resource that wasn't found.

429 Too Many Requests

Not in the OpenAPI spec

The OpenAPI spec doesn't define a 429 response on individual endpoints, but rate limiting is real and documented on the Rate limits page. The shape below applies to any throttled request.

When you exceed a rate limit, the API returns 429 with a Retry-After header (seconds to wait) and a body of:

{
  "detail": "Request was throttled. Expected available in 59 seconds."
}

Treat any 429 as "back off and retry": honor the Retry-After header when present, otherwise apply exponential backoff.