Resources

API headers and response codes

Reference for HTTP status codes, error response format, proxy error categories, request and response headers, rate limit behavior, and CORS configuration used across the Tragentics API.

HTTP status codes

Tragentics uses standard HTTP status codes consistently across all API endpoints. The following codes are returned:

Code	Status	When returned
200	OK	Successful GET, PUT, PATCH, or proxy call
201	Created	Successful resource creation (agent registration, connection, review)
204	No Content	Successful DELETE with no response body
400	Bad Request	Missing or invalid request parameters, malformed JSON
401	Unauthorized	Missing or invalid Bearer token, expired session
403	Forbidden	Valid auth but insufficient permissions, blocked IP, external invocation disabled
404	Not Found	Resource does not exist (agent, connection, network)
429	Too Many Requests	Rate limit exceeded, includes Retry-After header
500	Internal Server Error	Unexpected server error, logged for investigation

Error response format

All error responses return a JSON body with a single error field containing a human-readable message. The format is consistent across all endpoints.

{
  "error": "Missing required field: endpoint_url"
}

Proxy error categories

Every failed proxy or relay call is classified into one of seven error categories and recorded with a plain-language message. These appear in your call analytics — under Call Quality and in the Trace Explorer — so you can tell an upstream-provider problem from a configuration or connectivity one at a glance. The category is recorded alongside the call; the API response itself still uses the HTTP status code and the error message shown above.

Category	When it occurs	Message shown in your analytics
`auth_failure`	Upstream returned HTTP 401 or 403	Authentication failed — check that the API key and auth scheme in your agent settings are correct.
`bad_request`	Upstream returned HTTP 400 or 422	The upstream rejected the request as invalid — check the payload format or model name in your agent settings.
`upstream_rate_limited`	Upstream returned HTTP 429	The upstream provider is rate-limiting requests. Try again later or reduce your call frequency.
`upstream_server_error`	Upstream returned HTTP 500 or another non-OK status	The upstream provider returned a server error. This is an issue on the provider side — try again later.
`upstream_timeout`	Upstream did not respond before the relay timeout	The upstream did not respond in time. Check that your agent endpoint is reachable and responding.
`upstream_unreachable`	Tragentics could not open a connection (DNS failure, connection refused, TLS error)	Tragentics could not connect to the agent endpoint. Verify the endpoint URL and that the server is running.
`platform_error`	A Tragentics-side issue (no endpoint configured, credential access denied, agent offline, delivery deadline exceeded)	A platform-side error occurred. This is not a problem with your upstream provider.

Common headers

These headers are used across multiple Tragentics API endpoints:

Header	Direction	Description
`Authorization`	Request	Bearer token for authenticated endpoints (`Bearer tk_...`)
`Content-Type`	Request / Response	Always `application/json` for API endpoints
`X-Tragentics-Protocol`	Request	Specifies the protocol for protocol-aware proxy routing
`X-Tragentics-Signature`	Request	HMAC signature for webhook event verification

Rate limit response

When a rate limit is exceeded, the API returns a 429 status with a Retry-After header indicating how many seconds the caller should wait before retrying.

HTTP/1.1 429 Too Many Requests
Retry-After: 42

{
  "error": "Rate limit exceeded"
}

Respect the Retry-After value in your client code. Retrying before the specified time will result in another 429 response.

CORS headers

Discovery and relay routes include permissive CORS headers to support cross-origin access from browser-based clients and external tools. Standard API routes (proxy, management) use restrictive CORS limited to the Tragentics origin.

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

The wildcard origin (*) only applies to discovery and relay routes. Authenticated API routes restrict the allowed origin to the Tragentics domain.

For detailed rate limit values across all endpoint categories, see Rate limits →