Error codes

The full RepoErrorCode union with causes and retry semantics.

A complete reference of the RepoErrorCode union — unauthorized, forbidden, not_found, rate_limited, validation, unsupported, provider_error, and network_error — with typical causes and retry semantics.

Every failure throws a single type — RepoError — with a normalized code, so you branch on the failure without parsing provider-specific statuses or messages. For the conceptual overview see Errors; this page is the exhaustive reference.

The RepoError model

The code union

RepoErrorCode is a closed union of eight values:

unsupported and validation are frequently raised before any request is made — capability gating (query/owned/format/webhook events) and required-parameter checks (repo, ref, url, id) are enforced client-side.

retryable & retryAfter

retryable is a normalized hint. It defaults to true for rate_limited and network_error, and for provider_error when the HTTP status is 5xx. When the provider sent a Retry-After header, retryAfter carries the number of seconds to wait.

The client already performs one bounded retry on rate_limited when Retry-After is small (≤ 10s by default) — tune it via createClient({ provider, retry: { rateLimit, maxRetryAfterSeconds } }). For anything beyond that, build your own back-off from retryable and retryAfter.

Secret redaction

RepoError redacts known secrets from its message before construction — tokens and API keys the SDK knows about are replaced with [redacted] so they don’t leak into logs or error trackers.

Handling errors

import { RepoError } from 'repo-sdk';

try {
  await client.repos.get({ repo: 'capawesome-team/repo-sdk' });
} catch (error) {
  if (error instanceof RepoError) {
    switch (error.code) {
      case 'rate_limited':
        // back off using error.retryAfter
        break;
      case 'unauthorized':
        // refresh credentials and retry
        break;
      case 'not_found':
        // repository or resource doesn't exist
        break;
      case 'unsupported':
        // the active provider lacks this capability
        break;
      default:
        if (error.retryable) {
          // transient — safe to retry with back-off
        }
    }
  }
  throw error;
}