Troubleshooting

Use this page for high-frequency integrator mistakes. Prefer fixing the request shape over guessing from message text.

Wrong environment or key prefix#

Symptom	Fix
403 with an API-key error	Staging → `https://api-stg.vudy.app` + `vudy_sandbox_…`; production → `https://api.vudy.app` + `vudy_production_…`
Key starts with `vudy_stg_` / `vudy_prod_`	Replace it with a dashboard-issued `vudy_sandbox_…` / `vudy_production_…` key

Missing session vs missing headers#

Symptom	Fix
401 on a session-only route	Add a valid `Authorization: Bearer <session>` from OTP verification
401 on a conditional route without a session	Send both context headers if that route supports them, or use a team-scoped key
403 saying session/profile context is required	Confirm the route’s supported auth mode and provide that context
Context headers appear to be ignored	A valid session takes precedence; verify OTP again to change its profile

Insufficient permissions#

Symptom	Fix
403 names a required permission	Use a key granted that permission; do not try to work around the route restriction
403 on OTC provider APIs	Use a production key with `OTC_PROVIDER` and see Partner OTC

Maintenance or OTP gates#

Symptom	Fix
503 on `send-otp` / `verify-otp`	Check `GET /v1/maintenance`; retry after status is no longer `maintenance`
503 on `POST /channels/execute`	The KYC gate is closed; retry after maintenance status returns `ok`

Channel quote / execute failures#

Symptom	Fix
400 validation / signature	Refresh discovery/validation data and send parameters exactly as the capability describes
403 capability / onboarding	Confirm onboarding requirements and that the capability is enabled for your application
400 request body	Check that `capabilityId` is a UUID, `amount` is positive, and `params` is an object

Rate limits#

On 429, read Retry-After as seconds and do not retry before it elapses. SERVER_VALIDATION_API_AUTH_12 is the hourly limit; SERVER_VALIDATION_API_AUTH_19 is the burst limit. Retry mutations only when the endpoint documents that repeating them is safe.

Getting help#

Include the following when contacting support:

x-trace-id from the response headers
UTC timestamp, environment, HTTP method, and request path
HTTP status, error.code, and the sanitized error body
Reproduction steps and a sanitized request body when relevant

Never send a complete API key, session token, OTP, webhook secret, or other credential. If you include an API key identifier, provide only a short non-secret prefix.