SYNDERESIS / API OPERATE
Hosted customer API · Contract reviewed 7 November 2026
Production integration
On this page
Build around explicit time, cost and failure budgets. The examples are a starting point; your application owns end-user authentication, concurrency, external actions and its own service commitments.
Errors and remedies
Native API errors use this shape:
{
"error": {
"type": "unauthorized",
"code": "unauthorized",
"message": "Missing API key.",
"request_id": "example-request-id"
}
}
The illustrative message is abbreviated. type and code use the same machine code; message gives human guidance. Branch on status and code rather than matching message text. Keep the request_id for support. Internal suppliers and stack traces should not be needed to recover.
| HTTP and code | Meaning | Action |
|---|---|---|
| 400 invalid_request | Invalid JSON/object, missing/wrong fields, invalid transcript or a body over the endpoint limit. | Fix the request. Answers limit: 65536 bytes; 921600 bytes for chat completions. |
| 400 unsupported_model | The alias is not accepted on that path, for example labora with tools. | Use model discovery and the dispatch table. synderesis-pro is accepted as the same choice as pro. |
| 400 unsupported_parameter | On chat completions, automatic selection was combined with tools or tool results, or stream=true was sent on the answer path. | Choose an explicit tool-path model, or remove stream. POST /v1/answers ignores stream and tools. |
| 401 unauthorized | Missing, invalid, expired/revoked or conflicting credentials. | Correct the credential configuration. |
| 402 free_allocation_exhausted | The one-time starting token allocation is exhausted. | Subscribe through Account or confirm the applicable entitlement. |
| 402 insufficient_credit | Billable answer-path work cannot reserve enough account credit. | Add credit through Account and check your entitlement/tariff. |
| 402 inference_quota_exhausted | A shared inference-only key cannot admit the request under its lifetime cap. | Stop using that key; it does not refill. |
| 403 inference_scope_denied | A shared inference-only key called a route outside its scope. | Use it only for answers, chat completions and model discovery. |
| 403 origin_invalid / csrf_invalid | Browser session-origin/CSRF control failed. | Use the supported browser flow. Server-key calls should not carry a browser session. |
| 404 not_found | Unknown path or unavailable referenced resource. | Check the exact URL and API base. |
| 405 method_not_allowed | The path does not support that method. | Use the documented method; inspect Allow. Browser OPTIONS requests are not supported. |
| 429 quota_exceeded | An account/plan quota was reached. | Check allowance/plan/reset; repeated immediate attempts will not resolve it. |
| 429 rate_limited | A route-specific limiter rejected the request. | Wait, then retry within a bounded policy. |
| 503 service_unavailable | A dependency, quota subpath or generation operation could not complete. | Check health, use cautious bounded recovery and preserve the request ID. |
| 500 internal_error | An uncaught native boundary failure. | Preserve request ID; treat the result as uncertain and contact support if persistent. |
Some runtime-initialisation and boundary errors can occur before normal request handling. An unexpected response may be non-JSON due to infrastructure outside the application; handle that without exposing its body to end users.
Retries and uncertain outcomes
Do not automatically retry validation, authentication, unsupported-model or exhausted-allocation responses. Quota errors need a plan/reset remedy.
For a read-only model/lookup request where your application accepts possible duplicate compute and metering, use a small retry budget for transient failures. One reasonable client policy is an initial attempt plus at most two retries, exponential delay from 0.5 seconds, random jitter and an overall deadline. This is application guidance, not a Synderesis SDK/server default.
Honor Retry-After when present, but do not depend on it. Stop if a failure indicates exhausted capacity, a fixed invalid request or an unknown consequential action.
Idempotency-Key is used for accounting/reservation identity on generation paths. It is not a documented exactly-once generation guarantee or a cached-response replay API. Reusing it can encounter terminal or mismatched reservation state. Do not infer safe automatic regeneration from its existence.
A timeout or connection reset does not establish that the server performed no work. Reconcile usage and request IDs, and use a separate durable action ledger to avoid repeating external tool effects. Review and explicitly configure the retry behavior of any third-party SDK.
Timeouts and concurrency
Set connect/read/overall timeouts in your client and reverse proxy. The transcript/tool handler allows a longer upstream operation than the short answer handler; buffered SSE does not remove generation wait time.
Start with low concurrency and modest output caps. Increase only after observing latency, quota and credit behavior for your account. No universal concurrency or guaranteed latency figure is established by the reviewed public contract.
Pass through client cancellation for resource hygiene while preserving an uncertain-outcome state. Cancellation does not guarantee upstream cancellation or a refund.
Monitoring
Capture:
- Request ID and your own application correlation ID.
- Endpoint and public model alias.
- Status/error code, latency and attempt number.
- Returned token usage and account-level credit/allocation trends.
- Tool-loop turn count and independently tracked action results.
Use alerts for sustained failures, unexpected usage growth and quota/credit exhaustion. Avoid prompt or key logging. GET /health reports readiness and GET /v1/usage reports account state; neither is a complete production SLA.
Validate before launch
Confirm the exact model alias and handling path, conversation semantics, body/output limits and any function permissions. Exercise your parser with successful answers, empty source lists, nullable tool-call content, length finishes, unknown optional fields, error JSON and incomplete streams.
Test account/credit exhaustion in a suitable controlled setup. Reconcile a bounded sample of real account usage against your agreed tariff. Establish processor/retention terms and the support route.
Maintain an application rollback that can disable calls or switch to a separately qualified configuration without silently dropping user context or repeating consequential actions.
Contact and troubleshooting
Use hello@synderesis.eu with the UTC time, endpoint, HTTP status, public model alias and request ID. Include a redacted minimal request when necessary. Never include a real API key, cookie, private source text or unredacted user data.
The reviewed documentation does not establish a public status-page URL, service-level commitment, guaranteed support response time or automatic failover agreement.