vxcontrol/pentagi · error

unexpected status code: %d

Error message

unexpected status code: %d

What it means

handleErrorResponse maps known Perplexity API HTTP status codes to human-readable messages; the default branch produces 'unexpected status code: %d' for any status not in the explicit switch (400, 401, 403, 404, 405, 429, 500, 502, 503, 504). The caller (search) then classifies it: Retryable for 429 or >=500, Fatal otherwise. It signals an API-level failure surfaced through an undocumented status code.

Source

Thrown at backend/pkg/tools/searchers/perplexity.go:239

		return errors.New("API key is wrong")
	case http.StatusForbidden:
		return errors.New("the endpoint requested is hidden for administrators only")
	case http.StatusNotFound:
		return errors.New("the specified endpoint could not be found")
	case http.StatusMethodNotAllowed:
		return errors.New("there need to try to access an endpoint with an invalid method")
	case http.StatusTooManyRequests:
		return errors.New("there are requesting too many results")
	case http.StatusInternalServerError:
		return errors.New("there had a problem with our server. try again later")
	case http.StatusBadGateway:
		return errors.New("there was a problem with the server. Please try again later")
	case http.StatusServiceUnavailable:
		return errors.New("there are temporarily offline for maintenance. please try again later")
	case http.StatusGatewayTimeout:
		return errors.New("there are temporarily offline for maintenance. please try again later")
	default:
		return fmt.Errorf("unexpected status code: %d", statusCode)
	}
}

// formatResponse formats the API response into readable text
func (p *perplexity) formatResponse(ctx context.Context, response *CompletionResponse, query string) string {
	var builder strings.Builder

	// Checking for response choices
	if len(response.Choices) == 0 {
		return "No response received from Perplexity API"
	}

	// Getting the response content
	content := response.Choices[0].Message.Content
	builder.WriteString("# Answer\n\n")
	builder.WriteString(content)

	// Adding citations if available and within maxResults limit

View on GitHub (pinned to ea665308ba)

Solutions

1. Check the returned status code in the log and look it up in Perplexity's API documentation to identify the specific failure
2. If it is 402 Payment Required, top up the Perplexity account or check billing/credits
3. If 422, review the request payload (model name via PERPLEXITY_MODEL, search_context_size values) against current API requirements
4. Check the search orchestrator fallback — configure an alternative engine (e.g. SearxNG) in fallbackStrategy for resilience
5. Update the switch in handleErrorResponse to map newly observed status codes to explicit messages

Example fix

// before
case http.StatusGatewayTimeout:
    return errors.New("there are temporarily offline for maintenance. please try again later")
default:
    return fmt.Errorf("unexpected status code: %d", statusCode)
// after
case http.StatusGatewayTimeout:
    return errors.New("there are temporarily offline for maintenance. please try again later")
case http.StatusPaymentRequired:
    return errors.New("perplexity credits exhausted: check billing")
default:
    return fmt.Errorf("unexpected status code: %d", statusCode)

result, err := searcher.Handle(ctx, req)
var fatal FatalError
if err != nil {
    if errors.As(err, &fatal) {
        log.Printf("perplexity fatal error: %v", err) // switch engine
    } else {
        log.Printf("perplexity retryable error: %v", err) // retry/backoff
    }
    result, err = fallbackSearcher.Handle(ctx, req)
}

When it happens

Trigger: Perplexity returns a status code outside the mapped set, e.g. 402 Payment Required (credits exhausted), 408 Request Timeout, 422 Unprocessable Entity from a malformed request payload, or 418/5xx variants from edge infrastructure.

Common situations: Perplexity account out of credits or over quota returning 402; new API version introducing 422 validation errors; Cloudflare/WAF edge returning 520-527 codes not in the switch table.

Related errors

• unexpected status code: %d
• bearer scheme must be used
• token can't be empty
• Agentlogs.InvalidRequest
• Assistantlogs.InvalidRequest

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/3c2d4081adffd06c. Report an issue: GitHub.