> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stably.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Third-Party API Failures and Timeouts

> Simulate partner outages, slow responses, and bad payloads to validate resilient UX

Many production incidents come from third-party dependencies, not your own code. Playwright can simulate these failures so you verify graceful behavior before users see an outage.

## Failure Modes to Simulate

* Timeout from external API
* 5xx response from provider
* 429 rate limit
* Invalid payload shape
* Partial success (one request succeeds, next fails)

## Route Stubbing Pattern

Use `page.route` to intercept provider requests and force failure conditions.

```ts tests/resilience/maps-provider.spec.ts theme={null}
import { test, expect } from '@playwright/test';

test('shows fallback when maps API returns 503', async ({ page }) => {
  await page.route('**/maps-provider/**', async (route) => {
    await route.fulfill({
      status: 503,
      contentType: 'application/json',
      body: JSON.stringify({ error: 'service unavailable' }),
    });
  });

  await page.goto('/locations');
  await expect(page.getByText('Map unavailable')).toBeVisible();
  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
});
```

## Timeout Example

```ts theme={null}
test('shows timeout state for slow provider', async ({ page }) => {
  await page.route('**/credit-check/**', async (route) => {
    await new Promise((r) => setTimeout(r, 15000));
    await route.fulfill({ status: 504, body: 'timeout' });
  });

  await page.goto('/apply');
  await expect(page.getByText('Request timed out')).toBeVisible();
});
```

## Assertions That Matter

* User sees actionable message, not generic failure.
* Retry works and does not duplicate side effects.
* App remains responsive while waiting.
* Error is logged with enough metadata for support/debugging.

## Stably Features to Use for Resilience Monitoring

* Run resilience suites on [Stably Cloud](/run-tests/run-tests-on-cloud) with high parallelism to cover multiple providers quickly.
* Add [Scheduled Test Runs](/run-tests/scheduled-runs) for recurring synthetic outage drills.
* Configure [Alerts & Notifications](/run-tests/alerting) so third-party regressions are surfaced before customers report them.
* Use run artifacts in [Test Results](/run-tests/test-results) to inspect traces, screenshots, and failure context when fallback behavior breaks.