Error reference table
| Symptom | Recommended fix |
|---|---|
| 401 Unauthorized | Confirm the API key is valid, includes the mr_live_ prefix, and hasn't been revoked. |
| 403 Forbidden | The key belongs to another project or is inactive. Issue a new key for this integration. |
| Provider credentials not configured | Add the provider API key under Settings → Providers for the current project. |
| Structured output parsing errors | Validate your JSON schema, reduce complexity, or try a more capable model. Review the raw log entry to see the provider response. |
| Timeouts / slow responses | Configure workflow fallbacks so ModelRiver can retry with alternative providers. Monitor Observability for latency patterns. |
| Unexpected cached data | Ensure cache fields match the payload structure. Array indexes start at 0 (for example, messages.0.content). |
| Webhook not received | Verify the endpoint URL is correct and returns 2xx. Check Delivery & retries for retry status. |
| Webhook signature mismatch | Ensure the secret matches exactly (no extra spaces). Verify you're using the raw request body for signature computation. |
| Rate limit exceeded | ModelRiver enforces platform-wide rate limits. Contact support if you need higher throughput. |
| Empty AI response | Check that the provider has sufficient context. Verify the messages array format and model availability. |
Authentication quick fixes
API key issues
Bash
# Verify your key formatecho $MODELRIVER_API_KEY# Should start with mr_live_ # Test with curlcurl -H "Authorization: Bearer $MODELRIVER_API_KEY" \ https://api.modelriver.com/v1/ai \ -d '{"workflow": "test", "messages": [{"role": "user", "content": "hello"}]}'Provider credential issues
- Navigate to Settings → Providers
- Verify the provider shows a green checkmark
- If not, re-enter the credential and save
- Test with a simple request in the Playground
Next steps
- Debugging tips: Systematic debugging with Observability
- Contact support: Get help from the team
- API error handling: Full error code reference