Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

errors-and-retries

/errors-and-retries

Wyjaśnia kody błędów Subscriby, np. 401, 403, 409 i 429, które błędy ponawiać i jak zgłaszać problem z identyfikatorem żądania.

Licencja
MIT
Ostatnia zmiana repozytorium
09.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
5
Przestarzałość

Brak sygnałów. Repozytorium zmienione 09.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Wyjaśnia kody błędów Subscriby, np. 401, 403, 409 i 429, które błędy ponawiać i jak zgłaszać problem z identyfikatorem żądania.

Oryginalny opis (EN)

This skill should be used when the user asks what a Subscriby error code means, how to handle 401, 403, 404, 409, 422 or 429 answers, which errors to retry and how, what the error envelope carries, how to surface an error to a user or an agent, or how to report a problem with a request id.

Jak działa

  1. The codes
  2. The retry policy
  3. Surfacing errors
  4. Do not
  5. References
Sekcje z nagłówków SKILL.md, w oryginale · 63 linii, 680 słów
Podgląd SKILL.md
---
name: errors-and-retries
description: "This skill should be used when the user asks what a Subscriby error code means, how to handle 401, 403, 404, 409, 422 or 429 answers, which errors to retry and how, what the error envelope carries, how to surface an error to a user or an agent, or how to report a problem with a request id."
license: MIT
metadata:
  category: developers
  catalogue: 2026-05-01
---

# Errors and retries

Every error from `api.subscriby.net` and `mcp.subscriby.net` uses one envelope:

```json
{
  "error": {
    "code": "TOKEN_MISSING_ABILITY",
    "message": "The presented API token does not carry the ability required to perform this action.",
    "docs_url": "https://docs.subscriby.net/api/v1/errors#token-missing-ability",
    "remediation": "Mint a new token including the ability listed in error.required_ability, or ask the team owner to grant it.",
    "request_id": "00-abc...",
    "context": { "required_ability": "project:view" }
  }
}
```

Branch on `code`, a stable contractual string; `message` is free to change. `docs_url` anchors into the documentation, `remediation` is the one-sentence fix, `request_id` is what support needs, `fields` appears on `VALIDATION_FAILED` (each offending key with its rule failures) and `context` carries extras such as `required_ability`. The MCP server answers the same envelope inside a tool error.

## The codes

The generated [references/error-codes.md](references/error-codes.md) lists every code with its HTTP status, default message, remediation and docs anchor. The ones every integration meets:

| Code | Status | Meaning and what to do |
| --- | --- | --- |
| `VALIDATION_FAILED` | 422 | A field failed a rule: read `fields`, fix the input, do not retry as is. |
| `AUTHENTICATION_REQUIRED` | 401 | No bearer, a revoked token, or a token from the other environment: mint or refresh. |
| `TOKEN_MISSING_ABILITY` | 403 | The token lacks `context.required_ability`: mint one that carries it; never retry. |
| `FORBIDDEN` | 403 | The ability is there but the holder may not change this object (webhook endpoints belong to their registrant or the owner). |
| `TENANT_MISMATCH`, `RESOURCE_NOT_FOUND` | 404 | The id is outside the token's team or project list, or does not exist; existence is never leaked. Do not retry with other ids. |
| `IDEMPOTENCY_KEY_MISSING`, `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_REPLAY_IN_PROGRESS` | 400, 409 | A write without a key; the same key with a different body; a replay while the first request is still running. |
| `RATE_LIMITED` | 429 | Wait `Retry-After` seconds, then retry the same request with the same idempotency key. |
| `TEAM_TIER_REQUIRED`, `CONNECTOR_TIER_REQUIRED` | 402 or 403 as listed | The creator's plan does not include the feature; the fix is an upgrade, not a retry. |
| `PLAN_CURRENCY_MISMATCH`, `PLAN_PROVIDER_UNSUPPORTED`, `PAYMENT_METHOD_NOT_CONFIGURED` | as listed | A plan and a payment method disagree; read the message. |
| `ACCESS_CODE_INVALID`, `ACCESS_CODE_EXPIRED`, `ACCESS_CODE_ALREADY_REDEEMED`, `ACCESS_CODE_CAP_EXCEEDED` | as listed | A code's state; tell the member. |
| `CONNECTOR_UNAVAILABLE`, `CONNECTOR_NOT_INSTALLED`, `CONNECTOR_NOT_CONNECTED`, `IDENTITY_NOT_LINKED` | as listed | The platform side is not ready; the fix is on the project's Connectors page or the member's account. |
| `SUBSCRIPTION_ALREADY_ACTIVE` | as listed | The state already is what the call asked for; treat as success. |
| `WEBHOOK_ENDPOINT_UNREACHABLE` | as listed | The endpoint could not be reached at registration or test. |
| `METHOD_NOT_ALLOWED`, `INTERNAL_SERVER_ERROR` | 405, 500 | A wrong verb; a fault on Subscriby's side, retried with backoff and reported with `request_id`. |

## The retry policy

- Retry `429` after `Retry-After`, and `5xx` with exponential backoff and jitter, a bounded number of times.
- Never retry a `4xx` that is not a `429`; the input or the credential is wrong and a retry repeats the refusal.
- Send the same `Idempotency-Key` across retries of the same logical write, so a replay is free and a double charge impossible; use a fresh key for a different operation.
- Read `X-RateLimit-Limit` and `X-RateLimit-Remaining` to pace a batch below the per-token limits.

## Surfacing errors

Echo `code`, `message` and `docs_url` to a user or an agent's failure output; quote `request_id` to support. An agent should read `remediation` and act on it (mint, fix the input, wait) rather than retry blindly, and should read the resource `subscriby://enums/error-code` once per session so a code is recognised when it arrives.

## Do not

- Do not pattern-match on `message`.
- Do not retry a `TOKEN_MISSING_ABILITY`, a `TENANT_MISMATCH` or a `VALIDATION_FAILED` as it was.
- Do not drop `request_id` from logs; it is the only key support can trace.

## References

- [references/error-codes.md](references/error-codes.md): every code with status, message, remediation and docs anchor.
- Documentation: [error codes](https://docs.subscriby.net/api/v1/errors), [rate limiting](https://docs.subscriby.net/api/v1/rate-limiting), [status codes](https://docs.subscriby.net/reference/status-codes), [troubleshooting](https://docs.subscriby.net/reference/troubleshooting).
Pliki w paczce (2)
  • SKILL.md 5 KB
  • references/error-codes.md 8 KB

Wersje

W bazie nie ma innych skilli o nazwie errors-and-retries.

Migawka bazy z 13.11.2026 · wersja paczki d78db3fec6e4 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 90n8n
    Pomaga uruchomić Subscriby z n8n: instalacja węzła społecznościowego, konfiguracja danych dostępowych, wyzwalacz i gotowe przepisy.
  • 100webhooks
    Obsługuje webhooki Subscriby: rejestruje endpoint, weryfikuje nagłówek SB-Signature, ponowienia, rotację sekretu i błędy dostaw.
  • 100error-handling
    Opisuje wzorce solidnej obsługi błędów w TypeScript, Python i Go: typowane błędy, error boundaries, retry, circuit breakers i komunikaty o błędach dla użytkownika.
  • 95errors
    Projektuje spójne kody błędów w formacie PREFIX_KATEGORIA_NUMER oraz zasady obsługi błędów w API.
  • 100handle-errors
    Stosuje wzorce obsługi błędów w bazie kodu: walidację Zod na granicach, typowane błędy, wczesne zwroty oraz retry z backoffem.
  • 95go-error-handling
    Pomaga obsługiwać błędy w aplikacjach Go: opakowywanie błędów, błędy sentinel i własne typy błędów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.