Errors and trace IDs
Debug workflow API errors with confidence.
Zywrap API errors use a consistent JSON shape and include a trace ID. Use the trace ID when contacting support or searching server logs.
Error response format
Every API error returns a human-readable message, a machine-readable code, and a traceId. Some errors include safe details for client-side handling.
Normalized error response
{
"message": "Too many files requested for one run. Max allowed files per run is 10.",
"code": "V2_TOO_MANY_FILES_PER_RUN",
"traceId": "dd230c21-fa33-4b08-b521-3dd8c796f050",
"details": {
"limit": 10,
"received": 11
}
}Common workflow API error codes
| HTTP | Code | Meaning | Recommended action |
|---|---|---|---|
| 400 | V2_REQUEST_ERROR | Validation failed or resource was not found. | Check request body, path params, file IDs, and wrapper/model codes. |
| 401 | V2_UNAUTHORIZED | JWT missing/invalid or auth could not be verified. | Login again or send a valid API key using x-api-key. |
| 403 | V2_REQUEST_ERROR | API key disabled/revoked or user lacks required role. | Check API key state or admin permissions. |
| 402 | V2_INSUFFICIENT_CREDITS | No valid funding source in deduct mode. | Top up, upgrade plan, or enable BYOK where supported. |
| 409 | V2_SUBSCRIPTION_CONCURRENT_QUOTA_CONFLICT | Quota changed while processing billing. | Retry safely with the same idempotency key. |
| 413 | V2_RUN_INPUT_TOO_LARGE | Run input exceeded configured character limit. | Reduce input size or upload content as a file. |
| 415 | V2_UNSUPPORTED_CONTENT_TYPE | JSON endpoint did not receive application/json. | Set Content-Type: application/json and send a JSON body. |
| 429 | V2_RATE_LIMIT_EXCEEDED | Too many requests for the actor/route. | Use Retry-After and exponential backoff. |
| 500 | V2_INTERNAL_SERVER_ERROR | Unexpected server-side error. | Retry later and provide traceId to support. |
Auth failed
Old API keys without zw_live_ should use x-api-key. Bearer auth is best for JWTs and new zw_live_ keys.
Duplicate run
Use Idempotency-Key for POST /v2/runs. Same key returns the original run instead of re-executing.
Blocked admin route
Admin observability requires ADMIN or SUPER_ADMIN role. Normal users should receive 403.
Auth header examples
# Preferred for all API keys, including legacy keys
x-api-key: zw_live_...
# Also supported for new zw_live_ keys
Authorization: Bearer zw_live_...
# Dashboard sessions use JWT bearer auth
Authorization: Bearer <JWT>Rate limit response
HTTP/2 429
x-ratelimit-limit: 20
x-ratelimit-remaining: 0
x-ratelimit-reset: 1780742930
retry-after: 9
{
"message": "Too many V2 requests. Please slow down and retry shortly.",
"code": "V2_RATE_LIMIT_EXCEEDED",
"traceId": "..."
}When reporting an issue
Include the traceId, endpoint, approximate time, runId if available, and whether you used JWT, Bearer API key, or x-api-key.