Troubleshooting

This page covers common issues for both workflow-builder users and API integrators.

For endpoint-specific auth and schema requirements, always verify against the API Reference.

Authentication errors (401 / 403)

• 401 Unauthorized
  • Missing auth header
  • Invalid/expired token
  • Wrong API key value/header name
• 403 Forbidden
  • You’re authenticated, but you don’t have access to the organization/workspace or resource

Next steps:

1. Re-check which auth method the endpoint expects in the API Reference.
2. Confirm the org/workspace you’re targeting is correct.

API key issues

• Confirm the key is created in the same workspace you are calling
• Confirm header format (x-api-key or Authorization: Bearer pk_...)
• Confirm the endpoint supports API keys (currently contacts endpoints)

Debugging with request IDs

Orqio returns X-Request-Id on responses. When possible:

• Log the X-Request-Id
• Send your own x-correlation-id so you can trace calls end-to-end

See API Conventions.

Workflow run issues

• Run once in staging with controlled test data
• Open Executions and inspect failing node input/output
• Check credentials selected in each integration node
• Check required fields and validation warnings in node settings

Unexpected results or behavior changes

If an endpoint behavior changes unexpectedly:

1. Check the Changelog for relevant updates.
2. Confirm you’re using the correct environment/workspace.
3. Compare your payload with a known-good Example and reduce to a minimal reproduction.