Error Reference

The Tedro API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Response Format

All error responses follow this structure:

{
  "error": "A human-readable error message"
}

Validation errors include additional detail:

{
  "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"}

Fix: Sign in again to get a fresh session cookie. Ensure you include the x-workspace-id header on every request.

Permission Errors (403)

{"error": "Forbidden"}

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"}
  ]
}

Fix: Check the details array for specific field errors. Correct the request body and retry.

Conflict Errors (409)

{"error": "Contact with this phone number already exists"}

Fix: The resource you are trying to create conflicts with an existing one. Use a GET request to find the existing resource, or use a PATCH/PUT to update it instead.

Rate Limit Errors (429)

{"error": "Too many requests, please try again later"}

Fix: Wait for the duration specified in the 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"
}

Fix: Open the workflow in the visual builder and fix the reported issue. Every published workflow must have at least one 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

Overview

Workflows

Contacts

Conversations

Runs

Tags

Tools

Agents

Broadcasts

Groups

Settings: Channels

Settings: AI

Settings: Team

Settings: Workspace

Settings: Billing

Integrations

Templates

Metrics

Auth

Content

Errors

Error Reference

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Common Error Scenarios

Authentication Errors (401)

Permission Errors (403)

Validation Errors (400 / 422)

Conflict Errors (409)

Rate Limit Errors (429)

Workflow Validation Errors (422)

Error Handling Best Practices

​Error Reference

​Error Response Format

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Common Error Scenarios

​Authentication Errors (401)

​Permission Errors (403)

​Validation Errors (400 / 422)

​Conflict Errors (409)

​Rate Limit Errors (429)

​Workflow Validation Errors (422)

​Error Handling Best Practices

Error Reference

Error Response Format

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Common Error Scenarios

Authentication Errors (401)

Permission Errors (403)

Validation Errors (400 / 422)

Conflict Errors (409)

Rate Limit Errors (429)

Workflow Validation Errors (422)

Error Handling Best Practices