Errors: shape, codes, and what to do
The Flowyn error response shape, the HTTP status codes the API returns, and how failed outbound work is represented as resources instead of errors.
Error response shape
Every API error is JSON with a stable type, a specific code when one applies, a human message, the request_id, and whether retrying can help.
{
"error": {
"type": "invalid_request",
"code": "invalid_timeout",
"message": "timeout_ms must be between 100 and 30000.",
"request_id": "req_5f2a9c1e7b3d4a6f8e0c2b1d",
"class": "user",
"retryable": false
}
}Status codes
| Status | type | Meaning |
|---|---|---|
| 400 | invalid_request | The body is not valid JSON, a field has the wrong type, or the body is over 1 MiB (body_too_large). |
| 401 | unauthorized | Missing, malformed, or revoked API key. |
| 402 | billing_error | The monthly credit allowance is used (credit_limit_exceeded). Reads keep working. |
| 403 | forbidden | The key lacks the ability this call needs (ability_required). |
| 404 | not_found | The id does not exist in this environment. |
| 409 | conflict | For example idempotency_mismatch: the Idempotency-Key was used with a different body. |
| 422 | invalid_request | A field value is out of range, for example invalid_timeout. |
| 429 | rate_limited | Too many requests (rate_limit_exceeded). Wait for Retry-After seconds. |
| 5xx | server_error | Flowyn failed. The body carries an error_id to quote to support. |
Recovery information
Follow safe next guidance and use Retry-After before retrying a rate-limited request. Preserve request_id, error_id, and the original Idempotency-Key after a lost response. The SDK exposes idempotencyKey and retryAfterSeconds; CLI and MCP retain safe recovery fields. Canonical error documentation: https://flowyn.dev/docs/getting-started/errors.
Failed operations are resources, not errors
When an outbound HTTP call or a webhook delivery fails, your API request has already succeeded. The resource records the failed attempt and moves to retrying, then to its terminal status. Read the resource to see what happened. Repeated failures with the same fingerprint are grouped into an Issue.
Next step
Pick a product from the sidebar, or read the REST reference.