Errors

The one error envelope and the error codes the API serves at /docs/errors, with whether to retry.

Every error uses the same JSON envelope. Branch on code, which is stable. The message can change.

{
  "error": {
    "code": "insufficient_credits",
    "message": "The brand does not have enough prepaid balance to cover this post.",
    "fix": "Nothing was charged and no slot was used. Ask the brand to add funds, then submit again inside the window.",
    "docs_url": "/docs/errors#insufficient_credits",
    "retryable": false,
    "request_id": "..."
  }
}

When retryable is true, retry with exponential backoff. When it is false, change the request or the state first. A service that cannot be reached answers 503 provider_unavailable, and nothing is charged.

Codes

unauthorized

HTTP 401, not retryable. The API key is missing, malformed, revoked or unknown. Send a valid key in the Authorization header as "Bearer <key>". If the key was revoked, create a new one and retry.

forbidden

HTTP 403, not retryable. This API key is not allowed to make this request. Use a key from an account that has access to this product, or ask the account owner to grant access.

insufficient_credits

HTTP 402, not retryable. The account does not have enough credits for this lookup. Add credits to the account, then retry. Nothing was charged for this request.

rate_limited

HTTP 429, retryable. Too many requests for this API key. Wait the number of seconds in the Retry-After header, then retry. Spread requests out to stay under the X-RateLimit-Limit value.

invalid_input

HTTP 400, not retryable. The request input is invalid. Correct the field named in the message and resend. The fields each route takes are in the API reference. Nothing was charged.

unknown_product

HTTP 404, not retryable. No product exists at this path. Check the path against the routes in the API reference.

method_not_allowed

HTTP 405, not retryable. This endpoint does not accept that HTTP method. Use the method named in the Allow response header (lookup endpoints and /v1/mcp accept POST).

payload_too_large

HTTP 413, not retryable. The request body is too large. Send one lookup input per request and keep the JSON body small. Split large lists into separate requests.

provider_unavailable

HTTP 503, retryable. A service this request depends on, such as X or Stripe, cannot be reached right now. Nothing was charged. Email hello@viewpayout.com if it continues.

internal_error

HTTP 500, retryable. An unexpected error occurred. Retry once after a short wait. If it fails again, report the request_id to support. Nothing was charged.

not_found

HTTP 404, not retryable. Nothing exists at this address. Check the path and any ids in it against the API reference, then retry.

conflict

HTTP 409, not retryable. The request conflicts with the current state of the resource. Fetch the resource again, check its current state, then resend if the change still applies.

signature_invalid

HTTP 400, not retryable. The request signature is missing or does not match. Sign the exact raw request body with the signing secret this server was given and send the signature header.

plan_limit

HTTP 402, not retryable. The current plan does not allow this. Change to a plan that includes it, or reduce usage to stay within the plan, then retry.

subscription_required

HTTP 402, not retryable. This needs an active subscription. Subscribe from the billing page of the dashboard, then retry.

trial_expired

HTTP 402, not retryable. The free trial has ended. Subscribe from the billing page of the dashboard to keep using the service.