# Errors

All errors extend `UnicepError`.

| Error | When it happens |
| --- | --- |
| `InvalidCepError` | The value is not a CEP. No request is made. Has `input`. |
| `CepNotFoundError` | The CEP is valid, but no provider knows it. Has `cep`. |
| `AllProvidersFailedError` | No provider could answer. `error.errors` has one error per provider, in the order tried. |
| `ProviderError` | Thrown by a provider on failure. Has `provider` and `cause`. |
| `CircuitOpenError` | A provider was skipped because its circuit is open. Shows up in `AllProvidersFailedError.errors`. |

## Handling errors

```ts
import {
  AllProvidersFailedError,
  CepNotFoundError,
  InvalidCepError,
} from '@unicep/core';

try {
  const address = await unicep.lookup(input);
  show(address);
} catch (error) {
  if (error instanceof InvalidCepError) {
    // ask to double-check the CEP
  } else if (error instanceof CepNotFoundError) {
    // the CEP does not exist
  } else if (error instanceof AllProvidersFailedError) {
    // every service failed; see error.errors
    console.warn(error.errors);
  } else {
    throw error; // includes the reason of an AbortSignal cancellation
  }
}
```

## Cancellation

If you cancel with an `AbortSignal`, the promise rejects with the **abort reason** (by default
an `AbortError`), not with a unicep error. Circuit breakers are not affected.

## "Not found" or "failed"

- If every provider that answered said the CEP does not exist, the error is `CepNotFoundError`.
- If some failed and others said "not found", the error is `AllProvidersFailedError`, because we
  cannot say the CEP does not exist.
- A provider with an open circuit does not count as having answered.