Troubleshooting

Most embedded problems fall into three buckets: the request never authenticated, the connected user's credential went stale, or the workflow ran and failed. They surface in different places, so the first job is telling them apart.

The error envelope

Every embedded API error returns the same JSON shape, whatever the status code:

{
  "errors": [
    {
      "id": "9366efb4-8fb1-4a28-bfb0-8d6f9cc6b5c5",
      "status": "400",
      "code": "MISSING_REQUIRED_FIELD",
      "title": "Property values were not valid",
      "detail": "..."
    }
  ]
}

errors is an array - a single request can report more than one problem. id is the one field worth logging: it identifies that specific occurrence, and quoting it is the fastest way for support to find the failure. code is stable enough to branch on; title and detail are for humans and their wording can change.

What the status codes mean here

There is also a remote provider error response, used when the third-party API is what failed rather than ByteChef. Treat it as a signal to check the provider's own status, not your integration.

Authentication problems

Both credentials fail as a 401, but for different reasons:

• API Key - the key does not exist in that environment. Keys are environment-scoped, so a Development key against Production fails exactly like an invalid one.
• Signing Key JWT - the usual causes are an expired token (keep the TTL short and mint per session), a kid header that does not match a Signing Key, or signing with a rotated private key.

A disabled connected user is a distinct case: the token is valid and the user exists, but requests are refused until an admin re-enables them under Embedded → Connected Users. If a single customer is failing while everyone else is fine, check their enabled state first.

A JWT whose sub does not match the {externalUserId} segment of the request path (/api/embedded/v1/{externalUserId}/...) is also rejected with a 401, before the request reaches the endpoint. A token minted for one connected user cannot act on another user's path. Mint the token with the same id you put in the URL. The server URL-decodes the path segment before comparing.

Calling a frontend operation with an API Key is also rejected. Those paths carry no {externalUserId} segment, so there is no user for the key to act as - see the reference's authentication section.

Admin operations

Embedded admin operations require a tenant admin. This covers integrations, integration categories and tags, instance configurations, catalog projects, connected-user administration, App Events, workflow executions, connections administration, MCP servers, and Signing Keys. For any other ByteChef user, access is denied. If a teammate cannot manage these under Embedded in the ByteChef UI, check that their account has the admin authority (ROLE_ADMIN).

Credential problems

A connection whose credential has gone bad is marked INVALID - the only two states are VALID and INVALID. This is what a revoked OAuth grant, a rotated API key at the provider, or a password change looks like from ByteChef's side.

An invalid credential does not fail the API call that lists it; it fails the workflow that tries to use it. So the symptom a customer reports is "my automation stopped working", not an error in your UI. Two places show it:

• The Connected Users table has a status column and a filter for invalid credentials - see Connected Users.
• Your own app can read it per connection from Connections.

The fix is always the same: have the user reconnect through the Connect dialog, which replaces the credential in place.

Embedding problems

The workflow builder, Automation Hub and Integration Marketplace render in an iframe, so their failures show in the browser rather than in an API response:

• The iframe is blank and the console reports that a frame was refused because it violates frame-ancestors - your app's origin is not in BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS on the ByteChef server. Add the exact origin (scheme, host and port, no path) and restart the server.
• The page stays on its loading state - it never received EMBED_INIT from an allowed origin. Check that the origin your app runs on matches an entry in BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS exactly, including http versus https and the port. If the list is empty, the page announces itself only to your app's origin as reported in the iframe's referrer, so an app served with Referrer-Policy: no-referrer never hears from it; set the allowed parent origins.
• The console warns that no allowed parent origins are configured - BYTECHEF_EMBEDDED_ALLOWED_PARENT_ORIGINS is empty, so any website can embed the pages. Set it before going to production.

Execution problems

If the request authenticated and the credential is valid, the failure is in the run itself. Workflow executions record every step with its inputs, outputs, and error - see Workflow Executions for reading them, and Failures and Retries for what the engine does before a run is finally marked failed.

A checklist for a report you cannot reproduce

1. Which environment? Development, Staging, and Production hold entirely separate connected users, connections, and instances. A large share of "it does not exist" reports are the wrong environment.
2. Is the connected user enabled?
3. Is their connection VALID?
4. Did a run actually start? No execution record means the trigger never fired - check that the workflow is enabled for that user's instance.
5. What is the error id? With it, support can go straight to the occurrence.