Errors and retries

Non-successful requests use the canonical error envelope:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid domain format."
  },
  "data": {
    "field": "domain",
    "requestId": "1704b073-5bf1-4d64-8f9a-3af95edb3bf1"
  }
}

Every JSON error from the versioned API includes data.requestId. It is an opaque correlation ID that links the response to server logs; include it when contacting support, but do not use it for application branching. Other safe fields in data, such as retryAfter, are error-specific and optional. Branch on error.code; do not parse the human-readable message.

Common errors

HTTP status	Code	Recommended action
`400`	`VALIDATION_ERROR` or `INVALID_REQUEST`	Correct the request body, domain, IP address, or video URL before retrying
`401`	`UNAUTHORIZED`	Supply a valid OAuth access token or API key
`401` or `403`	`CAPTCHA_REQUIRED` or `CAPTCHA_FAILED`	Check that the integration sends a valid OAuth access token or API key; website verification is managed by Pirehub’s tools
`403`	`FORBIDDEN`	Check whether the key is active and has the scope required by the endpoint
`422`	`UNSUPPORTED_PLATFORM`	Use a supported public video platform
`422`	`UNPROCESSABLE_ENTITY`	Check that the video is public and can be processed
`422`	`MEDIA_UNAVAILABLE`	Check the original link: the media may have been removed, made private, or restricted; do not automatically retry
`429`	`RATE_LIMITED`	Wait for the per-minute window to reset
`429`	`MONTHLY_QUOTA_EXCEEDED`	Wait for the monthly reset or contact support
`500`	`INTERNAL_ERROR`	Retry later; contact support if the failure persists
`502`	`UPSTREAM_BAD_RESPONSE`	Retry because an upstream provider returned an unusable response
`503`	`SERVICE_UNAVAILABLE`	Retry because the requested service is temporarily unavailable
`504`	`UPSTREAM_TIMEOUT`	Retry because an upstream operation exceeded its deadline

Rate-limit responses

HTTP 429 covers more than one limit. Use error.code and, when present, data.reason to choose the correct recovery behavior.

Per-minute administrator-issued key limit

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please try again later."
  },
  "data": {
    "reason": "per_minute",
    "limit": 60,
    "remaining": 0,
    "resetAt": "2026-08-10T12:01:00.000Z",
    "retryAfter": 23,
    "requestId": "1704b073-5bf1-4d64-8f9a-3af95edb3bf1"
  }
}

Wait for retryAfter seconds or until resetAt before retrying.

Monthly administrator-issued key quota

{
  "success": false,
  "error": {
    "code": "MONTHLY_QUOTA_EXCEEDED",
    "message": "Monthly API request quota has been exhausted."
  },
  "data": {
    "reason": "monthly_quota",
    "limit": 10,
    "remaining": 0,
    "resetAt": "2026-09-01T00:00:00.000Z",
    "retryAfter": 1010458,
    "requestId": "1f4f2b4a-da4f-47d2-be0e-f85ddaeab6d4"
  }
}

Do not repeatedly retry a monthly quota failure. Wait until resetAt, or contact support to review the quota.

Browser or upstream throttling

Public browser traffic can be limited per IP address, and an upstream provider can also throttle a request. Those RATE_LIMITED responses may contain only data.retryAfter and data.requestId, or only data.requestId. The API-key-only fields reason, limit, remaining, and resetAt are therefore optional.

Data field	Meaning
`reason`	`per_minute` or `monthly_quota` for an API-key limit
`limit`	Maximum requests allowed in the affected API-key window
`remaining`	Requests remaining in that window; `0` when rejected
`resetAt`	Window reset time in ISO 8601 UTC format
`retryAfter`	Minimum wait in seconds when the server can calculate one
`requestId`	Correlation ID included in every JSON error

First-party client transport failures

The Pirehub web client can also classify failures that happen before an HTTP response exists. These codes are local transport outcomes, not server responses:

HTTP-equivalent status	Code or error name	Recommended action
`503`	`NETWORK_UNAVAILABLE`	Wait until the browser is online, then let the user retry
n/a	`AbortError`	Treat as caller cancellation; do not show a failure notification
n/a	`TimeoutError`	Tell the user the operation timed out and allow an explicit retry

The client does not queue authenticated or browser-verification mutations while offline. Tokens and business state may expire, and an automatic replay could duplicate a side effect.

Retry strategy

For 429, 503, and 504 responses, honor Retry-After when present. Otherwise, use exponential backoff with jitter and a finite retry limit. A monthly quota failure is not a transient retry candidate before its reset. Do not automatically retry 400, 401, or 403 responses until you have corrected the request or credentials. The first-party transport does not display notifications itself. Components decide whether an error is user-facing, which keeps background polling and prefetch failures from producing unrelated popups.

An unregistered domain is not an error. A completed lookup returns HTTP 200 with success: true and data.registered: false.

Self-service API plans

Subscription-backed API keys also return API_PLAN_REQUIRED or API_CAPABILITY_DENIED (403), API_CREDITS_EXCEEDED or USAGE_CONCURRENCY_EXCEEDED (429), and USAGE_RESERVATION_CONFLICT or USAGE_RESERVATION_EXPIRED (409). Rate limits and concurrency failures do not consume credits. Every error retains the same envelope and data.requestId. When admission returns USAGE_CONCURRENCY_EXCEEDED, it retains no new credit reservation; wait for capacity and retry with the same identifier and payload. See API plans, credits and idempotency for the full retry contract and header meanings.

Overview

Network intelligence

Video tools

Payment utilities

Screenshot tools

Social embeds

Web data

Common errors

Rate-limit responses

Per-minute administrator-issued key limit

Monthly administrator-issued key quota

Browser or upstream throttling

First-party client transport failures

Retry strategy

Self-service API plans

​Common errors

​Rate-limit responses

​Per-minute administrator-issued key limit

​Monthly administrator-issued key quota

​Browser or upstream throttling

​First-party client transport failures

​Retry strategy

​Self-service API plans

Common errors

Rate-limit responses

Per-minute administrator-issued key limit

Monthly administrator-issued key quota

Browser or upstream throttling

First-party client transport failures

Retry strategy

Self-service API plans