# Troubleshooting and request diagnostics

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

Canonical guide: <https://api.blackpearl.com/docs/troubleshooting>

Raw Markdown: <https://api.blackpearl.com/docs/raw/troubleshooting.md>

OpenAPI: <https://api.blackpearl.com/v1/openapi.json>

## 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 `-`:

```bash
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, tokens, cost, and latency. 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 code | Check | Next action |
|---|---|---|
| `missing_api_key` | The request has no Bearer header. | Add `Authorization: Bearer $BLACKPEARL_API_KEY` from the server-side secret store. |
| `invalid_api_key` or `expired_api_key` | Key was copied incorrectly, revoked, or expired. | Rotate to an active key; do not retry the unchanged credential. |
| `project_archived` or `forbidden` | Key project is archived or does not own the resource. | Use an active owning-project key. Cross-project IDs deliberately look missing. |
| `capability_disabled` | `GET /v1/capabilities` does not list the requested capability. | Ask an organization administrator to enable the entitlement. |
| `rate_limit_exceeded` | `RateLimit-Remaining` is `0`. | Wait at least `Retry-After`/`RateLimit-Reset`, then retry with jitter. |
| `quota_exceeded` | `error.details` identifies metric, scope, used, limit, and `resets_at`. | Wait for the UTC month reset or ask an administrator to change the quota. |
| `budget_exceeded` | `error.details` identifies spend, limit, hard-limit state, and `resets_at`. | Wait for reset or ask an administrator to change the hard budget. Do not use a rate-limit retry loop. |
| `insufficient_credits` | The billed organization had no positive balance at admission, or a completed run's actual charge exceeded the remaining balance. | Let auto-recharge complete or add prepaid credit before creating new work. |
| Job status `failed` | The 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 `503` | Capability 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`. |

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](https://api.blackpearl.com/docs/jobs), [Errors](https://api.blackpearl.com/docs/errors), and [Limits, budgets, and usage](https://api.blackpearl.com/docs/usage-quotas).

## 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 and 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.