Troubleshooting and request diagnostics

Correlate a failed call, inspect organization request records, and prepare a support-safe diagnostic package.

Capture a request ID#

Every response includes X-Request-ID; every public error repeats the same value as error.request_id. The gateway generates a value when the client does not send one. To correlate your own logs, send an ASCII identifier of 1-128 characters that starts with a letter or digit and then uses only letters, digits, ., _, :, or -:

REQUEST_ID="checkout:20260714:7f20"
curl --fail-with-body --silent --show-error \
  "$BLACKPEARL_API_BASE_URL/v1/capabilities" \
  --header "Authorization: Bearer $BLACKPEARL_API_KEY" \
  --header "X-Request-ID: $REQUEST_ID" \
  --dump-header -

The response echoes a valid client value. An invalid value is rejected as 422 invalid_request, and the response carries a newly generated safe ID. Request IDs are correlation values, not authentication or idempotency controls; use Idempotency-Key separately on job creation.

For accepted or rejected generation work, an organization console user can open Logs, paste the exact request ID into the search box, and inspect method, path, status, capability, time, and latency. What each run was charged is on the Costs page and in GET /v1/charges (see Billing and auto-recharge). Completion accounting can appear as another record correlated to the job ID. Read-only polling and authentication failures do not create Usage log rows, so retain the response ID for the support workflow below.

Diagnose by failure class#

Symptom or codeCheckNext action
missing_api_keyThe request has no Bearer header.Add Authorization: Bearer $BLACKPEARL_API_KEY from the server-side secret store.
invalid_api_key or expired_api_keyKey was copied incorrectly, revoked, or expired.Rotate to an active key; do not retry the unchanged credential.
project_requiredA company-level key with no default project sent a request that needs a project, without the Blackpearl-Project header.Send the header with the project's id or slug. Polling a job by its ID needs no header.
project_not_foundThe Blackpearl-Project header or project_ref names a project that doesn't exist in the organization.Check the id or slug with GET /v1/projects.
project_archived or forbiddenThe project is archived, or a project key named another project or called an operation only a company-level key can use.Use an active project, or the right key for it. A project key's request for another project's job or campaign returns not_found: cross-project IDs deliberately look missing.
capability_disabledGET /v1/capabilities shows the capability with enabled: false, or doesn't list it.Request access for your organization; organization roles can't enable a capability themselves.
rate_limit_exceededRateLimit-Remaining is 0.Wait at least Retry-After/RateLimit-Reset, then retry with jitter.
quota_exceedederror.details identifies metric, scope, used, limit, and resets_at.Wait for the UTC month reset or ask an administrator to change the quota.
budget_exceedederror.details identifies the scope, the kind of limit (day, month, allowance, or min_to_start), the project_id, charged spend, limit, and resets_at.Wait for resets_at, or ask an owner, administrator, or billing member to raise the budget or limit. A project allowance doesn't reset: top it up (see Managing your clients with projects). Do not use a rate-limit retry loop.
insufficient_creditsThe billed organization had no positive balance at admission. A completed run whose charge exceeded the remaining balance still succeeds and leaves the balance negative.Let auto-recharge complete or have an owner, administrator, or billing member add prepaid credit before creating new work.
Job status failedThe job's public error and request ID are safe to record.Stop polling, preserve the job ID, and correct non-transient input/configuration causes before creating new work.
Audience 502 or 503Capability service returned an invalid response/error or was unavailable.Retry a safe read with bounded backoff. For ambiguous creation, repeat the exact request with its persisted Idempotency-Key.
Transient 502/503/504, timeout, or connection error while polling a jobThe failure occurred in transit (CDN edge, load balancer, or an outbound proxy on your network); the platform job continues regardless.Retry the same GET /v1/jobs/{job_id} with bounded backoff and resume with the persisted job ID. Do not create a replacement job. If it recurs, capture the full response headers and body and include them in the support package below.

Never infer failure from a local polling timeout: it stops only the client. Keep the job ID and resume GET /v1/jobs/{job_id}. See Jobs and resumable polling, Errors, and Limits, budgets, and usage.

Prepare a support-safe package#

If the documented action does not resolve the problem, send the account's established support contact these values:

  • error.request_id or the X-Request-ID response value;
  • UTC timestamp, HTTP method, and path without sensitive query values;
  • HTTP status and error.code;
  • organization/project ID, the Blackpearl-Project value if you sent one, and the API-key prefix (never the secret key);
  • job/campaign ID and the non-secret Idempotency-Key, when relevant; and
  • a short reproduction sequence and whether the failure is repeatable.

Do not include the Bearer credential, cookies, full request bodies, candidate exports, or other confidential data. Support can correlate the request ID with platform request records; the package does not require you to access internal logs or source code.

No public status-page or generic support URL is configured in the current deployment metadata. Use the support channel named in your account agreement; public documentation will link dedicated destinations when they exist.