Documentation Index
Fetch the complete documentation index at: https://docs.tedro.io/llms.txt
Use this file to discover all available pages before exploring further.
Error Reference
The Tedro API uses standard HTTP status codes and returns errors in a consistent JSON format.
All error responses follow this structure:
{
"error": "A human-readable error message"
}
{
"error": "Validation failed",
"details": [
{
"path": "email",
"message": "Invalid email address"
},
{
"path": "name",
"message": "String must contain at least 1 character(s)"
}
]
}
HTTP Status Codes
Success Codes
| Code | Meaning | When |
|---|
200 | OK | Request succeeded (GET, PATCH, PUT, DELETE) |
201 | Created | Resource created successfully (POST) |
Client Error Codes
| Code | Meaning | Common Causes |
|---|
400 | Bad Request | Malformed JSON, missing required fields, invalid field values |
401 | Unauthorized | Missing or expired session cookie, missing x-workspace-id header |
403 | Forbidden | User lacks permission (e.g., Agent role trying to publish a workflow) |
404 | Not Found | Resource does not exist or belongs to a different workspace |
409 | Conflict | Duplicate resource (e.g., creating a contact with an existing phone number, creating a tag with an existing name) |
422 | Unprocessable Entity | Request is well-formed but semantically invalid (e.g., publishing a workflow with validation errors) |
429 | Too Many Requests | Rate limit exceeded — see Rate Limiting |
Server Error Codes
| Code | Meaning | What to Do |
|---|
500 | Internal Server Error | Unexpected server failure. Retry after a brief delay. If persistent, contact support. |
Common Error Scenarios
Authentication Errors (401)
{"error": "Unauthorized"}
x-workspace-id header on every request.
Permission Errors (403)
Fix: Check your user role. Agent and Viewer role users cannot publish workflows, manage tools, or modify settings. Ask an Admin or Org Owner to perform the action or upgrade your role.
Validation Errors (400 / 422)
{
"error": "Validation failed",
"details": [
{"path": "name", "message": "Required"}
]
}
details array for specific field errors. Correct the request body and retry.
Conflict Errors (409)
{"error": "Contact with this phone number already exists"}
Rate Limit Errors (429)
{"error": "Too many requests, please try again later"}
Retry-After response header before retrying. See Rate Limiting for details on limits per endpoint.
Workflow Validation Errors (422)
When publishing a workflow, the platform validates the graph structure:
{
"error": "Workflow validation failed: no reachable handoff node"
}
Error Handling Best Practices
- Always check the status code before parsing the response body
- Parse the
error field for a human-readable description
- Check
details on 400/422 responses for field-level validation errors
- Implement retry with backoff for 429 and 500 responses
- Log the full response for debugging — include status code, headers, and body
