Troubleshooting

The shape of an embedded API error, what the common failures mean, and where to look when a connected user reports that something is broken.

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.

problem_type is deprecated

Older responses also carry problem_type, which duplicates code. Read code.

What the status codes mean here

Status	In embedded, this usually means
401	The credential was rejected - a bad API Key, or a JWT that is expired, signed with the wrong key, or carries a `kid` that does not match a Signing Key.
403	The credential authenticated but is not allowed to do this. A disabled connected user also lands here.
404	The integration, instance, or workflow does not exist in the environment the request resolved to - the most common cause is a missing or wrong `X-Environment`.
409	The request conflicts with current state, e.g. creating an instance that already exists.
422	The request parsed but the values were not acceptable - a required input missing, or a value the provider rejects.
500	A ByteChef-side failure. Log the error `id` and send it to support.

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.

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.

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.

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

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.
Is the connected user enabled?
Is their connection VALID?
Did a run actually start? No execution record means the trigger never fired - check that the workflow is enabled for that user's instance.
What is the error id? With it, support can go straight to the occurrence.