Error Handling
The gateway returns standard HTTP status codes. All gateway-level errors include a JSON body with an error field.
Status codes
| Status | Error | Cause |
|---|---|---|
401 | Missing or invalid Authorization header | No Bearer token, or token is invalid/expired/revoked |
403 | Vendor access not approved or billing inactive | Your vendor access to this MLS hasn't been approved, was revoked, or billing is canceled |
404 | Server not found | Org slug or server slug doesn't match a registered server |
405 | Method not allowed | Only POST is accepted for MCP JSON-RPC requests |
429 | Rate limit exceeded | You've exceeded the MLS policy's per-minute, per-hour, or per-day rate limit |
502 | Failed to reach upstream MCP server | The MLS data feed is unreachable (network error or DNS failure) |
503 | Server is paused/inactive | The MLS has paused or deactivated their server |
504 | Gateway timeout | The upstream server didn't respond within 30 seconds |
Error response format
Gateway errors return JSON with an error field:
{
"error": "Missing or invalid Authorization header"
}Rate limit errors include additional context:
{
"error": "governance_rate_limit_exceeded",
"message": "MLS policy per_minute rate limit exceeded.",
"limit_name": "per_minute",
"retry_after": 42
}401 Unauthorized
A 401 response includes a WWW-Authenticate header pointing to the OAuth protected resource metadata:
WWW-Authenticate: Bearer resource_metadata="https://gateway.conduitapi.dev/.well-known/oauth-protected-resource"MCP clients that support RFC 9728 can use this to auto-discover the authorization server and initiate an OAuth flow.
Retry strategies
429 — Rate limit exceeded
Check the retry_after field in the response body (seconds). Wait that duration before retrying. Also check X-RateLimit-Reset for the reset timestamp.
502 — Upstream unreachable
Retry with exponential backoff. Start at 1s, max 30s. If the upstream is down, requests will fail until the MLS resolves the issue.
504 — Timeout
The upstream took >30s to respond. Retry once. Consider reducing the scope of your query (fewer results, simpler filters).
[i]Non-retryable errors