Errors, limits and retries

Every tool page lists the errors only that tool returns. This page lists the ones any address can return, the limits that apply everywhere, and the rules for trying again.

What an error looks like

Errors always give error (what went wrong), code (a name to branch on), where (the field or request path), tryThis (what to do next), retryable (whether waiting can help) and requestId (the value to find in Logs or quote to support). problems identifies individual fields when present. docs usually links to the section that explains the code. KEY_CREATOR_IS_A_MEMBER has no docs link; find it under Account and dashboard errors. why is an optional compatibility field for further explanation. Follow the HTTP status, Retry-After and tryThis when retrying.

A failed request answers with an HTTP status (a number that sums up the result, such as 404 for not found) and a JSON body explaining what went wrong and what to do next.

• error: what went wrong, in a sentence you can show to a person on your own team.
• code: a fixed name to branch on in your code, such as KEY_EXPIRED. The wording of error can change, the code does not.
• where: the exact field path when known, otherwise the public request path.
• tryThis: the next step to take.
• retryable: always true or false. True for 408, 429 and 5xx. Follow tryThis and Retry-After, and use the same Idempotency-Key when repeating work.
• requestId: the same value as the X-Request-Id header. Quote it to support; for recognised-key requests it matches the Request ID you can search on Logs. No recognised key means no business Logs row. An unavailable backend or overloaded logger cannot save a Logs row; quote the ID and time to support.
• problems: when field validation fails, the places that need fixing. Each one has a path (the exact place, such as /images/0), a problem and its own tryThis.
• docs: a link to the section that explains this code: what it means, the usual causes, how to fix it and a request that works. Add .txt before the # for the plain text page.

{
  "error": "The request body could not be used.",
  "code": "INVALID_FIELD",
  "where": "/sellerNotes",
  "retryable": false,
  "requestId": "dc2a9e33-c568-4c37-a101-78846411bc02",
  "tryThis": "Fix each place listed in problems, then send the request again.",
  "docs": "https://business.pcific.ai/docs/api-errors#doc-invalid-field",
  "problems": [
    {
      "path": "/sellerNotes",
      "problem": "\"sellerNotes\" must be text.",
      "tryThis": "Send \"sellerNotes\" as a string in quote marks."
    },
    {
      "path": "/images/0",
      "problem": "This photo id is not one of yours.",
      "tryThis": "Upload the photo again and use the id the upload gives you."
    }
  ]
}

4xx means the request needs fixing before you send it again. 5xx means the problem is on PCIFIC's side: wait and try again. 429 means you sent too much too fast: wait the number of seconds in the Retry-After header. Always branch on code, never on the wording of error.

Where errors show up

• Refused straight away: the request is answered with an error and no work started. Wrong key, wrong permission, a body that does not fit, a limit reached. Nothing is charged.
• Failed later: Orbit and Safeguard start work and answer 202 at once. If the work then fails, you see it when you read the result back, where the failed result carries the same error and tryThis. Each tool page says exactly where.
• Before the website passes it on: the website itself answers 413 BODY_TOO_LARGE and 502, 503 or 504 BACKEND_UNAVAILABLE in the same shape.

Errors any address can return

Each code below, and each tool's own codes, has a section of its own on the errors pages, starting with the mistakes integrations make most often.

• Errors: keys, credits and limits
• PixelTrace errors
• Safeguard errors
• Orbit errors
• Ask PCIFIC errors

PCIFIC approves your account before you can make keys. Approved company email domains and accepted team invitations skip the wait. Account approval is the only approval from PCIFIC. To go live, choose Live key on the API keys page and press Activate live key; live calls spend credits bought from PCIFIC. Staff can suspend and restore live-key access (LIVE_KEYS_OFF).

Response headers

Every API response includes X-Request-Id. Every error body includes the same value as requestId. This opaque UUID is the Request ID you can search on the dashboard Logs page. Recognised-key requests, including network limits and website refusals, are recorded when the backend and its logger are available. Refusal logging bounds key lookups and database concurrency; a logging outage or overload can leave an ID without a Logs row. Requests with no recognised key have no business to attach to Logs. A backend outage cannot be saved in Logs; quote its ID and time to support. RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset report an enforced request window, its requests left at the time it was checked, and seconds until it resets. If several windows were checked, the one with the fewest requests left is reported, choosing the earliest reset for a tie. Network, key, work-starting, sign-in, key-link and PixelTrace limits use their actual counters; a test key's daily AI cap resets at midnight UTC. Sign-in reports its public network allowance; private per-email controls are not exposed. Rate headers are omitted on publicly cacheable responses, such as badges, so a shared cache cannot pass one network's allowance to another. Headers are also omitted when no public request allowance was checked, including disabled limits. They describe request counts, not credit balances or file size limits. In-memory limits apply per server and reset on restart; PixelTrace and daily test counts are stored in the database.

When calling from scripts, send a User-Agent header naming your app, for example User-Agent: MyMarketplace/1.0.

Requests and addresses

For JSON tool requests, we recommend sending Content-Type: application/json; requests without it are read as JSON. The same input validation, work limits and charging rules apply with or without the header.

HEAD is supported wherever GET is supported. It returns the same status as GET and no body. Unknown API addresses, including unsupported API versions, return JSON NOT_FOUND with the same error fields.

The plain-text changelog at /changelog.txt accepts ?since=YYYY-MM-DD. An invalid or impossible date returns 400 INVALID_SINCE with where=/query/since. Send a real date, or omit since for the whole feed.

Limits

Every /api/v1 address has these limits a minute: 120 requests per API key that start work (POST /api/v1/listings, /api/v1/safeguard/reviews, the answers and retry calls of both, /api/v1/ask-pcific, /api/v1/pixel-trace/captures), a separate 600 PixelTrace photo-check requests per API key (they do not use AI or the work-starting allowance), 1,200 requests of any kind per API key (enough to read results back every few seconds; it only stops runaway loops), and 1,200 requests of any kind per network address (an IP address; IPv6 addresses count per /64). Requests refused before work starts, including bad input, missing fields and wrong types, do not use the work-starting allowance or the daily test AI cap. They still count towards the general per-key and network request limits. Photo-check requests, including invalid photos, use their own allowance before the image is opened. PixelTrace also allows 600 group starts and checks combined per account per minute, across all its keys. One key can use the full 600 for checks when no groups are started; group starts still share the 120 work starts with other tools. Authentication failures still count towards the network limit. Past any of them the API answers 429 RATE_LIMITED, naming the exact limit reached, with a Retry-After header saying how many seconds to wait. Send requests one after another rather than all at once, and give each environment its own key.

Each tool page adds its own limits, such as the number of photos in a PixelTrace group.

Free AI load tests with a test key

Send X-PCIFIC-Test-AI: stub on Orbit, Safeguard and Ask PCIFIC requests with a test key. Keep sending the header on follow-up actions. A listing or review keeps its starting mode; a mismatch returns TEST_AI_MODE_MISMATCH. Start a new job to change mode. Live keys and other values are refused with INVALID_TEST_AI_MODE. Authentication, shop isolation, input and schema validation, request and work limits, safe retries, database queues, result polling, streaming and Logs still run. Only the AI execution is replaced with a fixed, synthetic result. No model, web search or paid lookup runs. These requests spend no credits and use none of the shop’s daily AI allowance, even when it is already full. Normal rate limits still apply, so pace the test and follow Retry-After.

The response header repeats X-PCIFIC-Test-AI: stub. Started jobs carry a synthetic warning, finished results include testAiStub: true, and Logs labels the request as a synthetic AI load test. Orbit and Safeguard jobs keep this mode across restarts and retries. Synthetic listings do not promise to fit the schema; synthetic reviews must never be treated as approval. This measures your request path and PCIFIC's queue and storage, not model quality, real AI latency, inference capacity or paid tool performance. Remove the header for normal AI requests. Safeguard, Orbit and Ask PCIFIC stay on release 2.0.0.

Retrying safely

Sometimes you cannot tell whether a request worked: the connection dropped, or your server timed out. Sending it again could do the work twice. An Idempotency-Key (a unique value you choose for each piece of work) lets you send it again safely. PCIFIC does the work once and gives you the first answer again.

curl -X POST https://business.pcific.ai/api/v1/listings \
  -H "Authorization: Bearer $PCIFIC_TEST_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c2b9e-7d3a-4c55-9a51-0e6b2f8d1c47" \
  -d '{"notes":"iPhone 13 128GB, unlocked, good condition"}'

Send an optional Idempotency-Key on every public request that changes data or starts work: all POST, PUT and DELETE operations in the API reference, including Ask PCIFIC, PixelTrace checks, uploads, documents, settings and cancellations. Read-only GETs and the camera link validity check do not need one. Keys stay optional so existing integrations continue working; without a key, each call runs independently and a retry can repeat work and credits. Use 1 to 255 visible ASCII characters, such as a fresh UUID per action, and save it with the request before sending. Retry the same method, address (including query), body bytes and Content-Type within 24 hours to get the original successful status and body with Idempotent-Replayed: true, without more work or credits. Keep Accept and X-PCIFIC-Test-AI mode unchanged too. Upload retries must reuse the original bytes, including a multipart form's boundary. A different request with the same key returns 422 IDEMPOTENCY_KEY_REUSED with a next step. While work is running, 409 IDEMPOTENCY_KEY_IN_USE and Retry-After: 2 mean wait and retry with the same key. Keys belong to your business and test or live mode, shared across rotated API keys of that mode. marketplaceId is part of the request. Camera calls use a separate scope tied to the camera credentials; resend the original cookie and signed headers as well. Confirmation can replay with its original signature after the browser clears its cookie. Only successful replies are kept. A 4xx refusal is not saved. A replay of an accepted Orbit or Safeguard start returns the original 202 ticket. Poll the returned runId or reviewId for the current result. Refused requests and failures release the key, so fix the named problem and retry. An Ask PCIFIC stream is saved only when its done event arrives: retries replay all original events from the beginning, including done, without another answer or charge. Replace any partial answer in your interface when replaying. Work with a key continues after a dropped connection. Site-only demos and unavailable placeholder routes are outside this API contract.

Requests to send with a ticket

• POST /api/v1/webhooks
• PUT /api/v1/webhooks/{id}
• DELETE /api/v1/webhooks/{id}
• POST /api/v1/webhooks/{id}/rotate-secret
• POST /api/v1/webhooks/{id}/test
• POST /api/v1/embed-sessions
• PUT /api/v1/embed/branding
• POST /api/v1/embed/branding/scan
• POST /api/v1/marketplaces
• PUT /api/v1/marketplaces/{id}
• DELETE /api/v1/marketplaces/{id}
• PUT /api/v1/marketplace/settings
• PUT /api/v1/schema-draft/categories/{category}
• DELETE /api/v1/schema-draft/categories/{category}
• POST /api/v1/schema-versions/{version}/republish
• POST /api/v1/schema-versions
• PUT /api/v1/spend-limits
• POST /api/v1/ask-pcific
• PUT /api/v1/ask-pcific/settings
• PUT /api/v1/ask-pcific/item-source
• DELETE /api/v1/ask-pcific/item-source
• POST /api/v1/ask-pcific/item-source/test
• POST /api/v1/documents
• DELETE /api/v1/documents/{id}
• PUT /api/v1/documents/{id}/content
• PUT /api/v1/documents/{id}/tags
• POST /api/v1/documents/{id}/refresh
• POST /api/v1/documents/{id}/unpublish
• POST /api/v1/documents/{id}/publish
• POST /api/v1/documents/{id}/versions/{versionId}
• POST /api/v1/images
• DELETE /api/v1/images/{id}
• POST /api/v1/listings
• POST /api/v1/listings/{id}/answers
• POST /api/v1/listings/{id}/retry
• POST /api/v1/listings/{id}/cancel
• POST /api/v1/listings/{id}/outcome
• PUT /api/v1/orbit/settings
• POST /api/v1/safeguard/reviews
• POST /api/v1/safeguard/reviews/{id}/answers
• POST /api/v1/safeguard/reviews/{id}/retry
• PUT /api/v1/safeguard/settings
• POST /api/v1/pixel-trace/captures
• POST /api/v1/pixel-trace/captures/{captureId}/test-photos
• POST /api/v1/pixel-trace/captures/{captureId}/test-confirm
• POST /api/v1/pixel-trace/captures/{captureId}/complete
• POST /api/v1/pixel-trace/captures/{captureId}/retract
• POST /api/v1/pixel-trace/check
• PUT /api/v1/pixel-trace/settings
• POST /api/v1/pixel-trace/camera/{captureId}/open
• POST /api/v1/pixel-trace/camera/{captureId}/move
• POST /api/v1/pixel-trace/camera/{captureId}/shots
• POST /api/v1/pixel-trace/camera/{captureId}/photos
• DELETE /api/v1/pixel-trace/camera/{captureId}/photos/{photoId}
• POST /api/v1/pixel-trace/camera/{captureId}/cancel
• POST /api/v1/pixel-trace/camera/{captureId}/confirm

import { randomUUID } from "node:crypto";

// Persist this action before sending. Reload the same action after a crash.
const action = {
  key: randomUUID(),
  url: "https://business.pcific.ai/api/v1/ask-pcific",
  body: JSON.stringify({ question: "How much is delivery?" }),
};
async function send(action) {
  return fetch(action.url, {
    method: "POST",
    headers: {
      Authorization: "Bearer " + process.env.PCIFIC_API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": action.key,
    },
    body: action.body,
  });
}
const response = await send(action);
// On a lost response, call send(action) again. For 409, wait Retry-After.
console.log(response.status, await response.json());

import json, os, uuid, urllib.request

# Persist this action before sending. Reload it after a crash.
action = {
    "key": str(uuid.uuid4()),
    "url": "https://business.pcific.ai/api/v1/ask-pcific",
    "body": json.dumps({"question": "How much is delivery?"}).encode(),
}
def send(action):
    request = urllib.request.Request(action["url"], data=action["body"], method="POST", headers={
        "Authorization": "Bearer " + os.environ["PCIFIC_API_KEY"],
        "Content-Type": "application/json",
        "Idempotency-Key": action["key"],
    })
    return urllib.request.urlopen(request)

with send(action) as response:
    print(response.status, json.load(response))
# On a lost reply, call send(action) again. For 409, wait Retry-After.

When to try again

• 429: wait the seconds in the Retry-After header, then send the same request.
• 502, 503 and 504: wait and try again with backoff (waiting longer each time, for example 2, then 4, then 8 seconds). Stop after three tries. Send the same Idempotency-Key each time where the call takes one.
• 500: the same as 502 to 504. If it keeps happening, contact PCIFIC support with the time of the request.
• Any other 4xx: do not send the same request again. Change it first, using tryThis and problems.
• Never block your own seller or buyer on a PCIFIC error. Let them save and publish, and tell them in your own words that the check could not run.

Words used on this page

• HTTP status: the number at the start of an answer that sums up the result.
• Idempotency-Key: a unique value you choose for each piece of work, so a repeated request is not done twice.
• Backoff: waiting a little longer before each new try.
• UTC: the world time standard that days and limits are counted on.

Related guides

• Getting started
• Build it yourself
• API keys and permissions