Error Codes

Every error returned by api.subscriby.net and mcp.subscriby.net uses a uniform envelope:

{
  "error": {
    "code": "TENANT_MISMATCH",
    "message": "The requested resource does not belong to the team this API token is scoped to.",
    "docs_url": "https://docs.subscriby.net/api/v1/errors#tenant-mismatch",
    "remediation": "Use a token minted for the correct team, or switch the creator's current team before minting.",
    "request_id": "00-abc...",
    "context": { "required_ability": "project:view" }
  }
}

Fields:

• code — stable string identifier. Pattern-match on this.
• message — human-readable summary. Free to change between releases.
• docs_url — anchor into this page.
• remediation — one-sentence hint for self-correction.
• request_id — trace identifier. Share with support when filing an issue.
• fields — only present on VALIDATION_FAILED. Maps each offending key to a list of rule-failure messages.
• context — only present when the thrower supplied extra context (e.g. required_ability on TOKEN_MISSING_ABILITY, project_id on TENANT_MISMATCH).

ValidationCopy Anchor Link

VALIDATION_FAILEDCopy Anchor Link

• HTTP status: 422
• When: The request body failed a validation rule (missing required field, bad enum value, wrong type).
• Remediation: Inspect error.fields — each offending key maps to an array of failure messages.

Authentication & authorizationCopy Anchor Link

AUTHENTICATION_REQUIREDCopy Anchor Link

• HTTP status: 401
• When: No Authorization: Bearer sbt_live_... header is present, or the token has been revoked.
• Remediation: Mint a fresh token at /settings/tokens and retry.

TOKEN_MISSING_ABILITYCopy Anchor Link

• HTTP status: 403
• When: The token is valid but does not carry the ability required for this endpoint or tool.
• Context: required_ability — the exact ability string to grant.
• Remediation: Mint a replacement token that includes the listed ability, or ask the team owner to grant it.

FORBIDDENCopy Anchor Link

• HTTP status: 403
• When: The token carries the right ability and can see the resource, but its holder may not change it. Today this applies to webhook endpoints: only the member who registered an endpoint, or the team owner, may rotate, test or delete it.
• Remediation: Ask the endpoint's creator or the team owner to make the change, or mint the token as that member.

TENANT_MISMATCHCopy Anchor Link

• HTTP status: 404
• When: The token's scope:team:<uuid> does not match the team that owns the resource, the token is missing scope:team:<uuid> entirely, or scope:project:<uuid> excludes the project.
• Remediation: Use a token minted for the correct team. The response is 404 (not 403) so existence outside the scope cannot be inferred.

RESOURCE_NOT_FOUNDCopy Anchor Link

• HTTP status: 404
• When: The UUID in the path does not exist (or is hidden by scope).
• Remediation: Verify the UUID path parameter.

Domain validationCopy Anchor Link

PLAN_CURRENCY_MISMATCHCopy Anchor Link

• HTTP status: 400
• When: A plan's currency is not supported by any payment method attached to its project.
• Remediation: Change the plan's currency, or enable a payment method that supports it.

PLAN_PROVIDER_UNSUPPORTEDCopy Anchor Link

• HTTP status: 400
• When: The billing cycle is not supported by the provider (e.g. monthly recurring on a one-off-only provider).
• Remediation: Pick a different provider, or switch to a one-off plan.

PAYMENT_METHOD_NOT_CONFIGUREDCopy Anchor Link

• HTTP status: 400
• When: Publishing a plan that has no enabled payment method on its project.
• Remediation: Configure at least one payment method on the project before publishing the plan.

SUBSCRIPTION_ALREADY_ACTIVECopy Anchor Link

• HTTP status: 400
• When: Creating or updating a subscription for a subscriber who already has an active subscription on the project.
• Remediation: Cancel the existing subscription first, or update its plan instead.

Access codesCopy Anchor Link

ACCESS_CODE_INVALIDCopy Anchor Link

• HTTP status: 400
• When: The redemption code is unknown or does not match the project.
• Remediation: Verify the code is spelled correctly and belongs to this project. Codes are case-sensitive.

ACCESS_CODE_EXPIREDCopy Anchor Link

• HTTP status: 400
• When: The code's expiry has passed.
• Remediation: Generate a new batch of access codes with a fresh expiry window.

ACCESS_CODE_ALREADY_REDEEMEDCopy Anchor Link

• HTTP status: 400
• When: The code has already been used. Access codes are single-use.
• Remediation: Generate a new code for the subscriber.

ACCESS_CODE_CAP_EXCEEDEDCopy Anchor Link

• HTTP status: 400
• When: The creator's monthly access-code generation quota is exhausted.
• Remediation: Upgrade the creator's tier for a higher allotment, or wait for the next cycle.

IdempotencyCopy Anchor Link

IDEMPOTENCY_KEY_MISSINGCopy Anchor Link

• HTTP status: 400
• When: A mutating endpoint (POST / PATCH / PUT / DELETE) was called without an Idempotency-Key header.
• Remediation: Generate a fresh UUID, send it as Idempotency-Key, retry.

IDEMPOTENCY_KEY_REUSEDCopy Anchor Link

• HTTP status: 409
• When: The same Idempotency-Key was used previously with a different request body.
• Remediation: Use a fresh key per distinct operation.

IDEMPOTENCY_REPLAY_IN_PROGRESSCopy Anchor Link

• HTTP status: 425
• When: A prior request with the same key is still running; the server is serialising concurrent retries.
• Remediation: Wait briefly and retry.

Request shapeCopy Anchor Link

METHOD_NOT_ALLOWEDCopy Anchor Link

• HTTP status: 405
• When: The path exists but does not accept the verb you used — a POST to a read-only collection, say, or a PUT where the endpoint takes PATCH.
• Remediation: Check the endpoint reference for the verbs the path accepts. The response carries an Allow header listing them.

ThrottlingCopy Anchor Link

RATE_LIMITEDCopy Anchor Link

• HTTP status: 429
• When: The token (or IP for unauthenticated routes) exceeded its bucket. See rate limiting.
• Remediation: Back off per the Retry-After header.

TierCopy Anchor Link

TEAM_TIER_REQUIREDCopy Anchor Link

• HTTP status: 403
• When: An operation requires the creator's account to be on a higher Subscriby tier (e.g. Growth for custom handles or advanced RBAC).
• Remediation: Upgrade the creator's account from /settings/billing.

ConnectorsCopy Anchor Link

CONNECTOR_UNAVAILABLECopy Anchor Link

• HTTP status: 422
• When: POST /v1/projects/{project}/connectors/{key} or install_connector named a connector creators may not install today: a roadmap entry, one still in development, or one paused during an incident. context.connector echoes the key.
• Remediation: Read GET /v1/connectors; only a card whose installable is true can be installed.

CONNECTOR_TIER_REQUIREDCopy Anchor Link

• HTTP status: 403
• When: A second distinct connector was installed on a project whose owner's plan lacks the multi_connector capability. Official connectors are free; running two on one project is a Growth feature.
• Remediation: Upgrade the project owner from /settings/billing, or uninstall the project's other connector first.

CONNECTOR_NOT_INSTALLEDCopy Anchor Link

• HTTP status: 404
• When: An installation endpoint or tool named a connector that exists but the project does not run. Distinct from RESOURCE_NOT_FOUND with reason: unknown_connector, which says the key names no connector at all. context.connector and context.project_id say which.
• Remediation: Install it first (POST /v1/projects/{project}/connectors/{key}), or read GET /v1/projects/{project}/connectors for what the project runs.

WebhooksCopy Anchor Link

WEBHOOK_ENDPOINT_UNREACHABLECopy Anchor Link

• HTTP status: 502
• When: The synchronous webhook test call could not reach the target URL.
• Remediation: Verify the endpoint is HTTPS-reachable from the public internet.

ServerCopy Anchor Link

INTERNAL_SERVER_ERRORCopy Anchor Link

• HTTP status: 500
• When: Unexpected server-side failure.
• Remediation: Capture error.request_id and contact support. All 5xx errors are auto-reported to the internal error tracker.