Troubleshooting

401 Missing provider api key

Meaning:

• the public edge session route did not receive x-api-key

Check:

• x-api-key is present

401 Invalid provider API key, not found

Meaning:

• the provider key is wrong or unknown

Check:

• you are using the correct provider API key
• on normal product API routes, you are sending it as x-api-key
• on session issuance, you are sending it as x-api-key

401 Provider API key is not allowed for tenant

Meaning:

• the provider key is not scoped to that tenant or its parent integration tenant

Check:

• tenantId is correct
• the provider key belongs to the integration tenant that owns the managed team

401 Unknown embedded user

Meaning:

• (providerId, sub) does not exist and autoProvision was not enabled

Check:

• sub is the stable external user id you expect
• either pre-provision the user or use ?autoProvision=true

403 Managed team context required, set x-team-id to the target team

Meaning:

• you called a team-scoped product API route without selecting a managed team

Check:

• x-team-id is present
• it points to a property-manager team, not the integration tenant itself

404 App '<id>' not found On Connection Create

Check:

• appId came from GET /apps
• the id is exact
• you are not using a display name instead of the app id

Session Issued But Iframe Calls Fail

Check:

• the iframe uses the returned accessToken, not the provider API key
• requests go to https://api.edge.vrplatform.app
• the token has not expired
• the token was issued for the same tenantId the iframe is trying to open

400 On GET /teams/issues

Check:

• every team id in tenantIds is a valid uuid
• every code in codes is one of the documented issue codes

Ingest Submit Fails

Check:

• you are using Authorization: M2M <jwt>
• the token has ingest:submit
• tenantId and connectionId are valid
• the payload matches the selected ingest entity route
• the request uses the outer ingest envelope, not just a raw entity payload