Error Reference
Teamday API error objects, request IDs, idempotency errors, rate-limit behavior, and retry guidance.
Error Reference
Teamday API responses include X-Request-Id. Log it and include it when debugging a failed request.
Error Object
Current API middleware returns structured errors:
{
"type": "https://docs.teamday.ai/api/errors#rate_limited",
"code": "rate_limited",
"message": "Too many API requests in the current rate-limit window.",
"status": 429,
"request_id": "req_9b2c2d5d-3e3a-4a34-8a85-55b53a6f8e0a",
"details": {
"retry_after_seconds": 41
}
}Some route handlers still return compact legacy bodies such as:
{
"error": "not authenticated"
}Retry Rules
| Status | Retry? | Agent behavior |
|---|---|---|
400 | No | Fix the request body, query, or header. |
401 | No | Refresh credentials or prompt for reauthorization. |
403 | No | The token lacks access to the requested org, workspace, or resource. |
404 | No | Re-check the resource ID and organization context. |
409 | Maybe | For idempotency conflicts, do not retry with the same key unless the request body is identical. |
429 | Yes | Back off until Retry-After or RateLimit-Reset. |
500-599 | Yes | Retry with exponential backoff and the same Idempotency-Key for mutating calls. |
Idempotency Errors
| Code | Meaning | Recovery |
|---|---|---|
invalid_idempotency_key | Header is longer than 255 characters | Generate a shorter key |
idempotency_conflict | Key was reused with different input | Use the original request or generate a new key |
idempotency_in_progress | Same key is still running | Wait briefly, then retry the identical request |
Scope Errors
Scoped service tokens that lack access return 403 with a WWW-Authenticate scope hint:
WWW-Authenticate: Bearer error="insufficient_scope", scope="jobs:write"{
"type": "https://docs.teamday.ai/api/errors#insufficient_scope",
"code": "insufficient_scope",
"message": "The service token does not include a scope required for this API operation.",
"status": 403,
"request_id": "req_...",
"details": {
"required_scopes": ["jobs:write"],
"token_scopes": ["jobs:read"]
}
}Successful replays include:
Idempotency-Status: replayedRate-Limit Errors
When throttled, Teamday returns 429 with transparent quota headers:
Retry-After: 41
X-RateLimit-Limit: 900
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1779330180
RateLimit-Policy: 900;w=60Agents should wait for Retry-After seconds before retrying.
Webhook Delivery Errors
Webhook receivers should return 2xx only after durable acceptance. Teamday retries transient failures with backoff and includes:
Teamday-Event-Id: 01HX...
Teamday-Event-Type: job.done
Teamday-Delivery-Attempt: 2
Teamday-Signature: t=1779330180,v1=<hex-hmac-sha256>Use Teamday-Event-Id for deduplication.