Error Handling

Overview

The Perplexity SDKs provide robust error handling with specific exception types for different error scenarios. This guide covers how to catch and handle common API errors gracefully.

Common Error Types

The SDKs provide specific exception types for different error scenarios. All of them inherit from PerplexityError:

APIConnectionError - Network connection issues. APITimeoutError (Python) or APIConnectionTimeoutError (TypeScript) is raised when a request times out
APIStatusError (Python) or APIError (TypeScript) - Base class for HTTP status errors (4xx, 5xx)
BadRequestError - 400, invalid request parameters
AuthenticationError - 401, invalid API key or authentication issues
PermissionDeniedError - 403
NotFoundError - 404
ConflictError - 409
UnprocessableEntityError - 422
RateLimitError - 429, rate limit exceeded
InternalServerError - 500 and above
APIResponseValidationError (Python only) - The response did not match the expected schema

In TypeScript, check error types with instanceof against the classes exported from the package, such as Perplexity.RateLimitError.

Basic Error Handling

Handle common API errors with try-catch blocks:

import perplexity
from perplexity import Perplexity

client = Perplexity()

try:
    search = client.search.create(query="OpenAI o-series reasoning model benchmarks")
    print(search.results)
except perplexity.APIConnectionError as e:
    print("Network connection failed")
    print(e.__cause__)
except perplexity.RateLimitError as e:
    print("Rate limit exceeded, please retry later")
except perplexity.APIStatusError as e:
    print(f"API error: {e.status_code}")
    print(e.response)

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

try {
    const search = await client.search.create({ query: "OpenAI o-series reasoning model benchmarks" });
    console.log(search.results);
} catch (error) {
    if (error instanceof Perplexity.APIConnectionError) {
        console.log("Network connection failed");
        console.log(error.cause);
    } else if (error instanceof Perplexity.RateLimitError) {
        console.log("Rate limit exceeded, please retry later");
    } else if (error instanceof Perplexity.APIError) {
        console.log(`API error: ${error.status}`);
        console.log(error.error);
    } else {
        throw error;
    }
}

Response

{
  "id": "169d5d3b-272a-46ca-a59d-7c218f9d5ce2",
  "results": [
    {
      "snippet": "",
      "title": "Reasoning best practices | OpenAI API",
      "url": "https://developers.openai.com/api/docs/guides/reasoning-best-practices",
      "date": null,
      "last_updated": "2026-05-21"
    },
    {
      "snippet": "",
      "title": "A Comparative Study on Reasoning Patterns of OpenAI's o1 Model",
      "url": "https://arxiv.org/html/2410.13639v1",
      "date": "2024-10-17",
      "last_updated": "2026-03-22"
    },
    {
      "snippet": "**OpenAI o1** is a generative pre-trained transformer (GPT), the first in OpenAI's \"o\" series of reasoning models.\nA preview of o1 was released by OpenAI on September 12, 2024.\no1 spends time \"thinking\" before it answers, making it better at complex reasoning tasks, science and programming than GPT-4o.\nThe full version was released to ChatGPT users on December 5, 2024.\n...\nOpenAI noted that o1 is the first of a series of \"reasoning\" models.\nOpenAI shared in December 2024 benchmark results for its successor, o3 (the name o2 was skipped to avoid trademark conflict with the mobile carrier brand named O2).\n...\no1 spends additional time thinking (generating a chain of thought) before generating an answer, which makes it better for complex reasoning tasks, particularly in science and mathematics.\n...\nOpenAI's test results suggest a correlation between accuracy and the logarithm of the amount of compute spent thinking before answering.\no1-preview performed approximately at a PhD level on benchmark tests related to physics, chemistry, and biology.\nOn the American Invitational Mathematics Examination, it solved 83% (12.5/15) of the problems, compared to 13% (1.8/15) for GPT-4o.\nIt also ranked in the 89th percentile in Codeforces coding competitions.\no1-mini is faster and 80% cheaper than o1-preview.\nIt is particularly suitable for programming and STEM-related tasks, but does not have the same \"broad world knowledge\" as o1-preview.\nOpenAI noted that o1's reasoning capabilities make it better at adhering to safety rules provided in the prompt's context window.\n...\nAccording to OpenAI's assessments, o1-preview and o1-mini crossed into \"medium risk\" in CBRN (biological, chemical, radiological, and nuclear) weapons.\nDan Hendrycks wrote that \"The model already outperforms PhD scientists most of the time on answering questions related to bioweapons.\"\n...\nAccording to OpenAI, o1 may \"fake alignment\", that is, generate a response that is contrary to accuracy and its own chain of thought, in about 0.38% of cases.\n...\nBy changing the numbers and names used in a math problem or simply running the same problem again, LLMs would perform somewhat worse than their best benchmark results.\nAdding extraneous but logically inconsequential information to the problems caused a much greater drop in performance, from −17.5% for o1-preview and −29.1% for o1-mini, to −65.7% for the worst model tested.",
      "title": "OpenAI o1 - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/OpenAI_o1",
      "date": "2024-09-12",
      "last_updated": "2026-03-31"
    },
    {
      "snippet": "",
      "title": "OpenAI O3 & O4 Mini: The First True Reasoning Agents? - YouTube",
      "url": "https://www.youtube.com/watch?v=TGnPcObHdLY",
      "date": "2025-04-16",
      "last_updated": "2026-04-08"
    },
    {
      "snippet": "",
      "title": "Safety",
      "url": "https://openai.com/index/learning-to-reason-with-llms/",
      "date": "2024-09-12",
      "last_updated": "2026-03-29"
    },
    {
      "snippet": "",
      "title": "Introducing OpenAI o3 and o4-mini",
      "url": "https://openai.com/index/introducing-o3-and-o4-mini/",
      "date": "2025-04-16",
      "last_updated": "2026-05-16"
    },
    {
      "snippet": "",
      "title": "OpenAI's o3 model scores 3% on the ARC-AGI-2 benchmark ...",
      "url": "https://forum.effectivealtruism.org/posts/CoPNbwNqDai6orZhv/openai-s-o3-model-scores-3-on-the-arc-agi-2-benchmark",
      "date": "2025-05-01",
      "last_updated": "2026-05-17"
    },
    {
      "snippet": "Built to handle hard problems — they take more time to think before responding, similar to how a person would approach a difficult task.\nThe “ OpenAI o1 preview ” model, specifically, shows incredible results for various hard problems: math, coding, and reasoning.\n...\nToday, OpenAI released the full version of the o1 model, making it production-ready for a wide range of use cases.\nIn this article, we’ll compare its capabilities with GPT-4o and Claude 3.5 Sonnet to see if it lives up to the claim.\n...\nWe compared these models across three key tasks:\nReasoning riddles, Math Problems, and Classifying customer tickets\nAlong the way, we explored the latest benchmarks, evaluated input and output token costs, assessed latency and throughput, and shared guidance on choosing the best model for your needs.\nFor up-to-date rankings, check our leaderboard , or keep reading to see the results of our evaluation.\nFrom this analysis we learn that:\nProduction apps: For apps in productions, we still recommend sing GPT-4o over o1, at least for one-off tasks like the ones we tested here.\nReasoning riddles: OpenAI o1 showed some inconsistency, refusing to answer one question and scoring 60% accuracy, similar to GPT-4o, though the difference isn’t major.\nGPT-4o is a great model for this task.\nClaude 3.5 Sonnet scored a lower accuracy of 56%.\n- Math equations: GPT-4o and the o1 model performed equally well on this task, raising questions about whether the higher cost of o1 is justified.\n- Surprisingly, the latest Claude 3.5 Sonnet lagged significantly behind, achieving only 39% accuracy on these examples.\n- Classification : All models performed similarly: GPT-4o (74%), O1 (73%), and Model 3.5 Sonnet (76%), with GPT-4o improving by 12% since September.\n- GPT-4o had the highest precision (86%) making it ideal for tasks where correct possitive predictions matter most.\nThe o1 model led in recall (82%) making it suitable when you need to capture as many TRUE cases as possible.\nThe Claude 3.5 Sonnet had best F1 score (77%) indicating robust overall classification performance.\n- Speed &amp; Cost: Given that we saw similar results across the three tasks we evaluated, we still can’t justify the cost of o1, and we recommend going with GPT-4o for most use-cases.\n- Complex Problems: Use OpenAI o1 when you need top-tier reasoning and latency isn’t a concern.\nIt’s ideal for agentic workflows with a “planning” stage, where the model creates a detailed plan that smaller, cheaper models can follow\n...\nAs expected, the new o1 models are slower due to their “reasoning” process.\nThis isn’t a drawback necessarily—it just makes them better suited for tasks where thoughtful problem-solving is essential.\nOpenAI o1 is approximately 30 times slower than GPT-4o.\nSimilarly, the o1 mini version is around 16 times slower than GPT-4o mini.\n## Cost comparison\nIt's evident that using OpenAI o1 will cost roughly 6x more than GPT-4o and Claude 3.5 Sonnet for input tokens, and about 5x more for output tokens.\n## Throughput (Output speed)\nOpenAI o1 stands out with the fastest throughput, generating 143 tokens per second.\nHowever, take this throughput data with a grain of salt — while its output speed is significantly higher than the other models, its latency, or time-to-think, is about 30x longer than GPT-4o and Claude 3.5 Sonnet.\n...\nWhen new models are released, we learn about their capabilities from benchmark data reported in the technical reports.\nThe new OpenAI o1 model improves on the most complex reasoning benchmarks:\nExceeds human PhD-level accuracy on challenging benchmark tasks in physics, chemistry, and biology on the GPQA benchmark Coding is easier — It ranks in the 89th percentile on competitive programming questions (Codeforces) It’s also very good at math — In a qualifying exam for the International Mathematics Olympiad (IMO), GPT-4o correctly solved only 13% of problems, while the reasoning model scored 83%.\nNow, this is next level.\nOn the standard ML benchmarks , it has huge improvements across the board:\n...\nThey’ve gathered over 6,000 votes, and the results show that the OpenAI o1 model is consistently ranked #1 across all categories, with Math being the most notable area of impact.\nThe o1-mini model is #1 in technical areas, #2 overall.\nCheck out the full results on this link.\n...\nThe results show that the newest model is great at complex tasks, but not preferred for some natural language tasks — suggesting that maybe the model is not the best for every use-case.\n...\nGPT-4o and the o1 model performed equally well on this task, raising questions about whether the higher cost of o1 is justified.\nSurprisingly, the latest Claude 3.5 Sonnet lagged significantly behind, achieving only 39% accuracy on these examples.\n...\nOpenAI o1 showed some inconsistency, refusing to answer one question and scoring 60% accuracy, similar to GPT-4o, though the difference isn’t major.\nGPT-4o is a great model for this task.\nClaude 3.5 Sonnet scored a lower accuracy of 56%.\n...\nWe ran the evaluation to test if the models' outputs matched our ground truth data for 100 labeled test cases, and we can see that they all got similar accuracies.\nGPT-4o got 74, O1 got 73, Claude 3.5 Sonnet got 76 answers right from total of 100.\nThis reinforces the idea that smarter, more cost-effective models without a \"reasoning module\" like o1 can perform just as well as o1, but without the added expense.\nIn a similar evaluation in September of 2024, we evaluated that GPT-4o had lower accuracy, and classified only 62 of the 100 examples correctly.\nToday, we’re seeing at a 12% improvement on this task!\n...\nToday, O1 has more production-ready properties and is starting to becomemore valuable for production use cases—though it’s best suited for those who can tolerate higher latency and need to tackle the toughest challenges.\nGPT-4O, however, remains the go-to model for many of the production use cases we see in the market.",
      "title": "Analysis: OpenAI o1 vs GPT-4o vs Claude 3.5 Sonnet - Vellum",
      "url": "https://www.vellum.ai/blog/analysis-openai-o1-vs-gpt-4o",
      "date": "2024-12-17",
      "last_updated": "2026-05-21"
    },
    {
      "snippet": "",
      "title": "THE RELATIONSHIP BETWEEN REASONING AND PERFORMANCE",
      "url": "http://arxiv.org/pdf/2502.15631.pdf",
      "date": null,
      "last_updated": "2025-02-25"
    }
  ],
  "server_time": null
}

Common HTTP status codes: 400 (Bad Request), 401 (Authentication), 403 (Permission Denied), 404 (Not Found), 429 (Rate Limit), 500+ (Server Error).

Advanced Error Handling

Exponential Backoff for Rate Limits

The SDKs already retry connection errors, 408, 409, 429, and 5xx responses twice by default, waiting for the Retry-After interval when the server sends one (see Configuration). The Python SDK only follows Retry-After values of 60 seconds or less and uses its own backoff for longer values; the TypeScript SDK follows any value. For custom retry logic, wait at least the Retry-After interval that a 429 response carries, and fall back to exponential backoff with jitter when the header is missing:

import time
import random
import perplexity
from perplexity import Perplexity

def search_with_retry(client, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.search.create(query=query)
        except perplexity.RateLimitError as e:
            if attempt == max_retries - 1:
                raise  # Re-raise on final attempt
            
            # Honor Retry-After when present, otherwise use exponential backoff with jitter
            retry_after = e.response.headers.get("retry-after")
            try:
                delay = float(retry_after) if retry_after else None
            except ValueError:
                delay = None
            if delay is None:
                delay = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Retrying in {delay:.2f} seconds...")
            time.sleep(delay)
        except perplexity.APIConnectionError:
            if attempt == max_retries - 1:
                raise
            
            # Shorter delay for connection errors
            delay = 1 + random.uniform(0, 1)
            print(f"Connection error. Retrying in {delay:.2f} seconds...")
            time.sleep(delay)

# Usage
client = Perplexity()
result = search_with_retry(client, "artificial intelligence")

import Perplexity from '@perplexity-ai/perplexity_ai';

async function searchWithRetry(
    client: Perplexity, 
    query: string, 
    maxRetries: number = 3
) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await client.search.create({ query });
        } catch (error) {
            if (attempt === maxRetries - 1) {
                throw error; // Re-throw on final attempt
            }

            if (error instanceof Perplexity.RateLimitError) {
                // Honor Retry-After when present, otherwise use exponential backoff with jitter
                const retryAfter = Number(error.headers.get('retry-after'));
                const delay = retryAfter > 0
                    ? retryAfter * 1000
                    : (2 ** attempt + Math.random()) * 1000;
                console.log(`Rate limited. Retrying in ${delay}ms...`);
                await new Promise(resolve => setTimeout(resolve, delay));
            } else if (error instanceof Perplexity.APIConnectionError) {
                // Shorter delay for connection errors
                const delay = (1 + Math.random()) * 1000;
                console.log(`Connection error. Retrying in ${delay}ms...`);
                await new Promise(resolve => setTimeout(resolve, delay));
            } else {
                throw error; // Don't retry other errors
            }
        }
    }
}

// Usage
const client = new Perplexity();
const result = await searchWithRetry(client, "artificial intelligence");

Error Context and Debugging

Extract detailed error information for debugging:

import perplexity
from perplexity import Perplexity

client = Perplexity()

try:
    response = client.responses.create(
        effort="low",
        input="Explain how the 10-year US Treasury yield is determined and how it influences mortgage rates."
    )
except perplexity.BadRequestError as e:
    print(f"Bad Request: {e.message}")
    print(f"Error Body: {e.body}")
    # Handle invalid request parameters

except perplexity.APIStatusError as e:
    print(f"Status Code: {e.status_code}")
    print(f"Error Message: {e.message}")
    print(f"Error Body: {e.body}")
    
    # Access raw response for detailed debugging
    print(f"Raw Response: {e.response.text}")
    print(f"Request ID: {e.response.headers.get('X-Request-ID')}")
    
except Exception as e:
    print(f"Unexpected error: {type(e).__name__}: {e}")

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

try {
    const response = await client.responses.create({
        effort: "low",
        input: "Explain how the 10-year US Treasury yield is determined and how it influences mortgage rates."
    });
} catch (error) {
    if (error instanceof Perplexity.BadRequestError) {
        console.log(`Bad Request: ${error.message}`);
        console.log(`Error Body: ${JSON.stringify(error.error)}`);
        // Handle invalid request parameters
    } else if (error instanceof Perplexity.APIError) {
        console.log(`Status Code: ${error.status}`);
        console.log(`Error Message: ${error.message}`);
        console.log(`Error Body: ${JSON.stringify(error.error)}`);
        
        // Response headers for detailed debugging
        console.log(`Request ID: ${error.headers?.get('X-Request-ID')}`);
    } else {
        console.log(`Unexpected error: ${error}`);
    }
}

Error Recovery Strategies

Graceful Degradation

Implement fallback mechanisms when API calls fail:

import perplexity
from perplexity import Perplexity

def get_ai_response(query, fallback_response="I'm sorry, I'm temporarily unavailable."):
    client = Perplexity()
    
    try:
        response = client.responses.create(
            effort="low",
            input=query
        )
        return response.output_text
        
    except perplexity.RateLimitError:
        return fallback_response
            
    except perplexity.APIConnectionError:
        # Network issues - return cached response or fallback
        return fallback_response
        
    except Exception as e:
        print(f"Unexpected error: {e}")
        return fallback_response

# Usage
response = get_ai_response("What is machine learning?")
print(response)

import Perplexity from '@perplexity-ai/perplexity_ai';

async function getAIResponse(
    query: string, 
    fallbackResponse: string = "I'm sorry, I'm temporarily unavailable."
): Promise<string> {
    const client = new Perplexity();
    
    try {
        const response = await client.responses.create({
            effort: "low",
            input: query
        });
        return response.output_text ?? fallbackResponse;
        
    } catch (error) {
        if (error instanceof Perplexity.RateLimitError) {
            return fallbackResponse;
        } else if (error instanceof Perplexity.APIConnectionError) {
            // Network issues - return cached response or fallback
            return fallbackResponse;
        } else {
            console.log(`Unexpected error: ${error}`);
            return fallbackResponse;
        }
    }
}

// Usage
const response = await getAIResponse("What is machine learning?");
console.log(response);

Best Practices

Always handle rate limits

Rate limiting is common with API usage. Always implement retry logic that waits for the Retry-After interval, with exponential backoff as a fallback.

Don’t implement aggressive retry loops without delays - this can worsen rate limiting.

Log errors for monitoring

Include proper logging to track error patterns and API health.

import logging
import perplexity
from perplexity import Perplexity

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = Perplexity()

try:
    result = client.search.create(query="discovery of penicillin by Alexander Fleming")
except perplexity.APIStatusError as e:
    logger.error(f"API Error {e.status_code}: {e.message}", 
                extra={'request_id': e.response.headers.get('X-Request-ID')})

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity();

try {
    const result = await client.search.create({ query: "discovery of penicillin by Alexander Fleming" });
} catch (error) {
    if (error instanceof Perplexity.APIError) {
        console.error(`API Error ${error.status}: ${error.message}`, {
            requestId: error.headers?.get('X-Request-ID')
        });
    }
}

Response

{
  "id": "cf46c6eb-bf6e-4ee4-97f8-9d4dcfd99dd4",
  "results": [
    {
      "snippet": "",
      "title": "Alexander Fleming Discovery and Development of Penicillin",
      "url": "https://www.acs.org/education/whatischemistry/landmarks/flemingpenicillin.html",
      "date": null,
      "last_updated": "2026-05-21"
    },
    {
      "snippet": "“*I did not invent penicillin.\nNature did that.\nI only discovered it by accident*.”\nAlexander Fleming was a Scottish physician-scientist who was recognised for discovering penicillin.\nThe simple discovery and use of the antibiotic agent has saved millions of lives, and earned Fleming – together with Howard Florey and Ernst Chain, who devised methods for the large-scale isolation and production of penicillin – the 1945 Nobel Prize in Physiology/Medicine.\n...\nIn 1928, Fleming began a series of experiments involving the common staphylococcal bacteria.\nAn uncovered Petri dish sitting next to an open window became contaminated with mould spores.\nFleming observed that the bacteria in proximity to the mould colonies were dying, as evidenced by the dissolving and clearing of the surrounding agar gel.\nHe was able to isolate the mould and identified it as a member of the *Penicillium* genus.\nHe found it to be effective against all Gram-positive pathogens, which are responsible for diseases such as scarlet fever, pneumonia, gonorrhoea, meningitis and diphtheria.\nHe discerned that it was not the mould itself but some ‘juice’ it had produced that had killed the bacteria.\nHe named the ‘mould juice’ penicillin.\nLater, he would say: “*When I woke up just after dawn on September 28, 1928, I certainly didn’t plan to revolutionize all medicine by discovering the world’s first antibiotic, or bacteria killer.\nBut I suppose that was exactly what I did*.”\nAlthough Fleming published the discovery of penicillin in the British Journal of Experimental Pathology in 1929, the scientific community greeted his work with little initial enthusiasm.\nAdditionally, Fleming found it difficult to isolate this precious ‘mould juice’ in large quantities.\nIt was not until 1940, just as he was contemplating retirement, that two scientists, Howard Florey and Ernst Chain, became interested in penicillin.\nIn time, they were able to mass-produce it for use during World War II.",
      "title": "Alexander Fleming (1881–1955): Discoverer of penicillin - PMC - NIH",
      "url": "https://pmc.ncbi.nlm.nih.gov/articles/PMC4520913/",
      "date": null,
      "last_updated": "2026-04-11"
    },
    {
      "snippet": "",
      "title": "Alexander Fleming - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Alexander_Fleming",
      "date": "2001-09-18",
      "last_updated": "2026-05-18"
    },
    {
      "snippet": "",
      "title": "Discovery of penicillin - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/Discovery_of_penicillin",
      "date": "2009-09-13",
      "last_updated": "2026-03-28"
    },
    {
      "snippet": "",
      "title": "The Discovery of Penicillin—New Insights After More Than 75 Years ...",
      "url": "https://pmc.ncbi.nlm.nih.gov/articles/PMC5403050/",
      "date": null,
      "last_updated": "2026-03-29"
    },
    {
      "snippet": "The accidental discovery of a mouldy petri-dish in 1928 kickstarted a 20-year long journey to develop the world’s first mass produced drug that could clear a bacterial infection; penicillin.\n...\nIn 1928 Dr Alexander Fleming returned from a holiday to find mould growing on a Petri dish of Staphylococcus bacteria.\nHe noticed the mould seemed to be preventing the bacteria around it from growing.\nHe soon identified that the mould produced a self-defence chemical that could kill bacteria.\nHe named the substance penicillin.\nFleming published his findings and presented his discovery to the Medical Research Club.\nTo his surprise, his peers showed little interest in his work.\n...\nNearly ten years later in 1937, while investigating microorganisms and the substances they produced, Howard Florey and Ernst Chain uncovered Fleming’s research and assembled a team of scientists to work solely on the 'Penicillin Project'.\n...\nThe mould produced six times more penicillin than Fleming’s original strain.\n...\nBy 1943, the US had sufficient penicillin stocks to satisfy the demands of the Armed Forces of the United States, as well as their Allies.\n...\nIn 1946 penicillin became available for the first time in the UK for public use, it transformed medicine worldwide and ushered in the age of antibiotics.",
      "title": "How was penicillin developed?",
      "url": "https://www.sciencemuseum.org.uk/objects-and-stories/how-was-penicillin-developed",
      "date": "2021-02-23",
      "last_updated": "2025-11-10"
    },
    {
      "snippet": "Eighty-three years ago today, Sir Alexander Fleming discovered penicillin, one of the most widely used antibiotics.\nInspired by what he saw on the battlefields of World War I, he went back to his laboratory at St. Mary’s Hospital in London to develop a way to fight bacterial infections.\nIn 1928, he accidentally left a petri dish in which he was growing Staphylococcus aureus bacteria uncovered.\nLater, he noticed that there was mold growing on the plate, and around the mold, the staph bacteria were dead.\nFleming isolated it and identified the mold as Penicillium notatum, a type of fungus that is similar to the mold that grows on bread.\nFleming published his findings in the British Journal of Experimental Pathology in 1929, but the report didn’t garner much interest.\nThen in 1938, Ernst Chain, a biochemist working with pathologist Howard Florey at Oxford University, came across Fleming’s paper while he was researching antibacterial compounds.\nScientists in Florey’s lab started working with penicillin, which they eventually injected into mice to test if it could treat bacterial infections.\nTheir experiments were successful and they went on to test it in humans, where they also saw positive results.\nBy 1941, there was an injectable form that could be used to treat patients, which was especially useful for soldiers fighting in World War II.\n...\nIn 1945, Fleming, Chain and Florey were awarded the Nobel Prize in Physiology or Medicine for “the discovery of penicillin and its curative effects in various infectious diseases”.\nFleming died in 1955.",
      "title": "Penicillin: 83 Years Ago Today",
      "url": "https://www.publichealth.columbia.edu/research/center-infection-and-immunity/penicillin-83-years-ago-today",
      "date": "2015-10-16",
      "last_updated": "2026-03-12"
    },
    {
      "snippet": "",
      "title": "History of penicillin - Wikipedia",
      "url": "https://en.wikipedia.org/wiki/History_of_penicillin",
      "date": "2006-03-31",
      "last_updated": "2026-04-08"
    },
    {
      "snippet": "Scottish bacteriologist Alexander Fleming is best known for his discovery of penicillin in 1928, which started the antibiotic revolution.\nFor his discovery of penicillin, he was awarded a share of the 1945 Nobel Prize for Physiology or Medicine.\n### How did Alexander Fleming discover penicillin?\nIn 1928 Alexander Fleming noticed that a culture plate of *Staphylococcus aureus* bacteria had become contaminated by a fungus.\nThe mold, later identified as *Penicillium notatum* (now classified as *P. chrysogenum*), had inhibited the growth of the bacteria.\nHe later established that the mold prevented bacterial growth because it produced an antibiotic, penicillin.\n...\n**Alexander Fleming** (born August 6, 1881, Lochfield Farm, Darvel, Ayrshire, Scotland—died March 11, 1955, London, England) was a Scottish bacteriologist best known for his discovery of penicillin.\n...\nHis work on wound infection and lysozyme, an antibacterial enzyme found in tears and saliva, guaranteed him a place in the history of bacteriology.\nBut it was his discovery of penicillin in 1928, which started the antibiotic revolution, that sealed his lasting reputation.\nFleming was recognized for that achievement in 1945, when he received the Nobel Prize for Physiology or Medicine, along with Australian pathologist Howard Walter Florey and German-born British biochemist Ernst Boris Chain, both of whom isolated and purified penicillin.\n...\nOn September 3, 1928, shortly after his appointment as professor of bacteriology, Fleming noticed that a culture plate of *Staphylococcus aureus* he had been working on had become contaminated by a fungus.\nA mold, later identified as *Penicillium notatum* (now classified as *P. chrysogenum*), had inhibited the growth of the bacteria.\nHe at first called the substance “mould juice” and then “penicillin,” after the mold that produced it.\nFleming decided to investigate further, because he thought that he had found an enzyme more potent than lysozyme.\nIn fact, it was not an enzyme but an antibiotic—one of the first to be discovered.\n...\nPenicillin eventually came into use during World War II as the result of the work of a team of scientists led by Howard Florey at the University of Oxford.",
      "title": "Alexander Fleming | Biography, Education, Discovery, Nobel Prize ...",
      "url": "https://www.britannica.com/biography/Alexander-Fleming",
      "date": "2026-04-24",
      "last_updated": "2026-04-25"
    },
    {
      "snippet": "Fleming’s serendipitous discovery of penicillin changed the course of medicine and earned him a Nobel Prize.\n...\nIn 1928 Alexander Fleming (1881–1955) discovered penicillin, though he did not realize the full significance of his discovery for at least another decade.\nHe eventually received the Nobel Prize in Physiology or Medicine in 1945.\n...\nIn 1928 Alexander Fleming discovered penicillin, made from the *Penicillium notatum* mold, but he did not receive the Nobel Prize in Physiology or Medicine for his discovery until 1945.\nFleming himself did not realize how important his discovery was; for a decade after, he focused instead on penicillin’s potential use as a topical antiseptic for wounds and surface infections and as a means of isolating certain bacteria in laboratory cultures.\n...\nFleming’s legendary discovery of penicillin occurred in 1928, while he was investigating staphylococcus, a common type of bacteria that causes boils and can also cause disastrous infections in patients with weakened immune systems.\nBefore Fleming left for a two-week vacation, a petri dish containing a staphylococcus culture was left on a lab bench and never placed in the incubator as intended.\nSomehow, in preparing the culture, a *Penicillium* mold spore had been accidentally introduced into the medium—perhaps coming in through a window, or more likely floating up a stairwell from the lab below where various molds were being cultured.\nThe temperature conditions that prevailed during Fleming’s absence permitted both the bacteria and the mold spores to grow; had the incubator been used, only the bacteria could have grown.\n...\nHe discovered that the antibacterial substance was not produced by all molds, only by certain strains of *Penicillium*, namely, *Penicillium notatum*.",
      "title": "Alexander Fleming | Science History Institute",
      "url": "https://www.sciencehistory.org/education/scientific-biographies/alexander-fleming/",
      "date": "2026-02-23",
      "last_updated": "2026-05-07"
    }
  ],
  "server_time": null
}

Set appropriate timeouts

Configure timeouts to prevent hanging requests.

import httpx
from perplexity import Perplexity

client = Perplexity(
    timeout=httpx.Timeout(connect=5.0, read=30.0, write=5.0, pool=10.0)
)

import Perplexity from '@perplexity-ai/perplexity_ai';

const client = new Perplexity({
    timeout: 30000 // 30 seconds
});

Handle authentication errors

Check for invalid API keys and provide helpful error messages.

try:
    result = client.search.create(query="Perplexity Search API Python SDK quickstart example")
except perplexity.AuthenticationError:
    print("Invalid API key. Please check your PERPLEXITY_API_KEY environment variable.")

try {
    const result = await client.search.create({ query: "Perplexity Search API Python SDK quickstart example" });
} catch (error) {
    if (error instanceof Perplexity.AuthenticationError) {
        console.log("Invalid API key. Please check your PERPLEXITY_API_KEY environment variable.");
    }
}

Configuration

Configure timeouts and retries

Best Practices

Environment variables and rate limiting

Getting Started

Orchestrator API

Agent API

Search API

Embeddings API

Decisions API

Perplexity SDK

Admin & Management

Resources

Overview

Common Error Types

Basic Error Handling

Advanced Error Handling

Exponential Backoff for Rate Limits

Error Context and Debugging

Error Recovery Strategies

Graceful Degradation

Best Practices

Configuration

Best Practices

​Overview

​Common Error Types

​Basic Error Handling

​Advanced Error Handling

​Exponential Backoff for Rate Limits

​Error Context and Debugging

​Error Recovery Strategies

​Graceful Degradation

​Best Practices

​Related Resources

Configuration

Best Practices

Overview

Common Error Types

Basic Error Handling

Advanced Error Handling

Exponential Backoff for Rate Limits

Error Context and Debugging

Error Recovery Strategies

Graceful Degradation

Best Practices

Related Resources