> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/api-reference/readme/error-and-reason-code-reference.md).

# Error and reason-code reference

Use stable error and decision reason codes to explain rejected requests, no-fill results, provider failures, fallback, retries, and recovery.

The **Podigee Audio Video Ad Server** uses stable names for API errors, decision reasons, provider results, and recovery actions. The code explains the state. A localized or user-friendly message can change without changing the code.

The machine-readable reason catalog and problem schemas are the authority. This article explains how to interpret them in an integration, support case, report, or delivery trace.

## Code rules

* Every code has a namespace and one meaning.
* Codes are append-only. A retired code is not reused for a different meaning.
* The code is separate from the translated explanation.
* The code identifies whether a retry is safe.
* A filled decision uses `candidate.selected`.
* A non-filled decision never uses `candidate.selected`.
* The first applicable category follows the declared reason precedence.

The same code can appear in an API problem, a decision trace, a report row, and a support case. Use the code when you compare systems.

## Error response shape

An API problem includes a stable problem type, code, safe message, and a trace or operation reference. It can also include the subject type, subject ID, current version, field path, retry class, and recovery link.

```json
{
  "type": "https://docs.podigee.com/problems/version-conflict",
  "code": "version.conflict",
  "message": "The Campaign version is no longer current.",
  "status": 409,
  "trace_id": "trace_demo",
  "operation_id": "op_demo",
  "subject": {
    "type": "campaign",
    "id": "campaign_demo",
    "version": 3
  },
  "retry": "read_current_version",
  "recovery": "Read the current version, review the difference, and submit a new command."
}
```

Do not expose secrets, raw identity, private provider payloads, or full internal stack traces in a problem response.

## Reason precedence

When several conditions fail, the decision uses the first applicable category in this order:

1. Request state.
2. Rights, consent, and authority.
3. Schedule.
4. Surface and format.
5. Creative and break readiness.
6. Publisher and brand safety.
7. Targeting.
8. Identity, frequency, and separation.
9. Reservation, budget, and pacing.
10. Demand.
11. Cost.
12. No eligible candidate.

This order gives one primary reason. Additional checks remain in the trace so an operator can see all relevant conditions without changing the user-facing explanation.

## Request and serving codes

| Code                                | Meaning                                                | Retry                                      |
| ----------------------------------- | ------------------------------------------------------ | ------------------------------------------ |
| `request.invalid`                   | The request does not match the public contract.        | No. Repair the request.                    |
| `request.signature_invalid`         | The signed request cannot be verified.                 | No. Repair the token or signature.         |
| `request.release_unknown`           | The request refers to a release that is not available. | Yes, after the active release is restored. |
| `request.capability_unknown`        | The requested capability is not declared.              | No. Select a supported capability.         |
| `publication.stale`                 | The publication version is no longer current.          | Yes, read the current version.             |
| `publication.revoked`               | The publication was revoked.                           | No, use the current active version.        |
| `serving.operator_pause`            | An operator paused serving.                            | Yes, after the operator resumes it.        |
| `serving.inventory_hold`            | The selected Inventory is on hold.                     | Yes, after the hold is cleared.            |
| `serving.creative_hold`             | The selected Creative is on hold.                      | Yes, after Creative checks pass.           |
| `serving.commercial_hold`           | A Commercial or finance rule blocks serving.           | Yes, after the rule is repaired.           |
| `serving.policy_hold`               | A workspace or publisher policy blocks serving.        | Yes, after policy review.                  |
| `serving.incident_hold`             | An incident policy blocks paid serving.                | Yes, after safe recovery.                  |
| `preflight.blocked`                 | The Campaign or Flight is not ready for publication.   | No, repair the named blocker.              |
| `delivery.compatibility_fallback`   | The client cannot use the selected paid presentation.  | No, use the declared compatible result.    |
| `delivery.source_fallback`          | Paid delivery failed and source content was used.      | No, inspect the delivery evidence.         |
| `delivery.representation_repairing` | The representation is being prepared or repaired.      | Yes, after preparation completes.          |
| `delivery.representation_dead`      | The representation is no longer available.             | No, use the current representation.        |
| `delivery.range_unsatisfiable`      | The requested byte range is not valid.                 | No, correct the range.                     |

## Rights, privacy, schedule, and format codes

| Code                              | Meaning                                             | Safe action                                  |
| --------------------------------- | --------------------------------------------------- | -------------------------------------------- |
| `authority.missing`               | Content or delivery authority is missing.           | Restore the source authority.                |
| `authority.revoked`               | The source authority was revoked.                   | Stop new serving and use the current source. |
| `authority.epoch_mismatch`        | The request uses an old authority epoch.            | Refresh the current state.                   |
| `rights.missing`                  | Required media or market rights are missing.        | Add valid rights or remove the target.       |
| `rights.expired`                  | The rights window ended.                            | Use a current Creative or rights version.    |
| `consent.restricted`              | The permitted data use does not cover this request. | Use the no-consent path.                     |
| `jurisdiction.restricted`         | The request is not permitted in the jurisdiction.   | Use the declared fallback.                   |
| `schedule.before_start`           | The Flight has not started.                         | Wait for the start or inspect the schedule.  |
| `schedule.after_end`              | The Flight has ended.                               | Use a current Flight.                        |
| `schedule.outside_window`         | The request is outside the active window.           | Check the time zone and schedule.            |
| `surface.unsupported`             | The destination cannot use the requested surface.   | Select a supported surface.                  |
| `format.unsupported`              | The media format is not supported.                  | Select a compatible rendition.               |
| `client.interstitial_unsupported` | The client cannot use the interstitial form.        | Use a compatible presentation.               |
| `media.profile_incompatible`      | The rendition does not match the surface profile.   | Prepare the required rendition.              |
| `media.apple_hls_package_invalid` | The Apple HLS package fails a required check.       | Repair the HLS package and validate again.   |

## Creative, policy, and targeting codes

| Code                                   | Meaning                                                     | Safe action                                          |
| -------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
| `break.unapproved`                     | The ad break is not approved for serving.                   | Review the break and its policy.                     |
| `break.binding_stale`                  | The break binding does not match the current media version. | Create a current binding.                            |
| `creative.unapproved`                  | The Creative is not approved.                               | Complete the configured review.                      |
| `creative.missing_rendition`           | No compatible audio or video rendition exists.              | Prepare and validate the rendition.                  |
| `creative.rights_invalid`              | Creative rights do not cover the request.                   | Repair the rights version.                           |
| `creative.universal_ad_id_missing`     | The required ad identifier is missing.                      | Add the governed identifier.                         |
| `creative.asset_unavailable`           | The referenced media asset is unavailable.                  | Restore or replace the asset.                        |
| `creative.scan_failed`                 | The security or media scan failed.                          | Review the scan result and upload a safe asset.      |
| `creative.malware_detected`            | The asset contains detected malware.                        | Keep it blocked and replace it.                      |
| `creative.validation_failed`           | The media or metadata validation failed.                    | Repair the exact reported field.                     |
| `publisher.category_blocked`           | The publisher policy blocks the category.                   | Use another eligible Creative or policy.             |
| `publisher.brand_blocked`              | The publisher policy blocks the brand.                      | Use another eligible demand source.                  |
| `brand.adjacency_blocked`              | The ad cannot appear beside the selected ad.                | Change the rotation or separation rule.              |
| `targeting.no_match`                   | The request does not match the target.                      | Review market, category, media, and surface values.  |
| `targeting.data_stale`                 | A required targeting input is too old.                      | Refresh the governed input.                          |
| `targeting.unknown_required_dimension` | The request lacks a required dimension.                     | Use the configured fallback or supply the dimension. |

## Frequency, reservation, demand, and cost codes

| Code                               | Meaning                                                | Retry                                        |
| ---------------------------------- | ------------------------------------------------------ | -------------------------------------------- |
| `identity.insufficient`            | The identity tier cannot support the rule.             | No. Use the disclosed fallback.              |
| `frequency.capped`                 | The identity reached its frequency cap.                | Yes, at a later eligible opportunity.        |
| `separation.pod_conflict`          | Another ad in the pod conflicts with this one.         | Yes, after the pod changes.                  |
| `reservation.conflict`             | The available capacity is reserved by another version. | Yes, after capacity changes.                 |
| `reservation.expired`              | The reservation is no longer active.                   | No, create or request a current reservation. |
| `budget.exhausted`                 | The budget is consumed.                                | No, wait for an approved budget change.      |
| `pacing.withheld`                  | Pacing withheld delivery to protect the goal.          | Yes, at a later opportunity.                 |
| `demand.timeout`                   | The provider did not answer within the limit.          | Yes, follow the retry policy.                |
| `demand.no_bid`                    | The provider returned no bid.                          | Yes, follow the demand order.                |
| `demand.invalid_response`          | The provider response failed validation.               | Yes, after the provider repairs it.          |
| `demand.bid_expired`               | The bid is no longer valid.                            | Yes, request a current bid.                  |
| `demand.circuit_open`              | The provider circuit is open after repeated failure.   | Yes, after the health window.                |
| `cost.circuit_open`                | The cost service is not safe to use.                   | Yes, after telemetry recovers.               |
| `cost.telemetry_stale`             | Cost telemetry is too old for the decision.            | Yes, after telemetry refresh.                |
| `measurement.evidence_invalidated` | Evidence no longer qualifies for measurement.          | No, reconcile the source.                    |
| `no_candidate.eligible`            | No candidate passed all checks.                        | Yes, when supply or demand changes.          |
| `candidate.selected`               | The candidate passed and was selected.                 | No. This is a successful selection.          |

## Provider and report codes

| Code                                         | Meaning                                                       | Safe action                                    |
| -------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------- |
| `report.destination_inactive`                | The report destination is not active.                         | Activate or replace the destination.           |
| `report.destination_unsupported`             | The destination does not support the report.                  | Select a supported destination.                |
| `report.destination_unavailable`             | The destination cannot accept the report now.                 | Retry within the report policy.                |
| `report.destination_rejected`                | The destination rejected the report.                          | Read the destination reason and repair it.     |
| `report.delivery_outcome_unknown`            | The final report delivery result is not known.                | Reconcile the delivery receipt.                |
| `integration.uncertified`                    | The capability has no current certification.                  | Complete certification before activation.      |
| `integration.documentation_pending`          | The provider contract is not complete enough to activate.     | Keep the capability blocked.                   |
| `integration.unsupported_capability`         | The provider does not support the requested capability.       | Select another capability.                     |
| `integration.apple_connect_contract_pending` | The Apple lifecycle contract is not available for activation. | Use the supported host-side path.              |
| `integration.spotify_capability_disabled`    | The Spotify capability is not enabled for the grant.          | Keep it inactive until enabled.                |
| `integration.spotify_ambiguous_create`       | The external create result is not known.                      | Reconcile the external resource before retry.  |
| `integration.spotify_processing_failed`      | Spotify processing failed.                                    | Read the provider result and repair the input. |
| `integration.spotify_cuepoint_conflict`      | The external cuepoint differs from the approved payload.      | Resolve the conflict before another write.     |

## Retry classes

The `retryable` property is part of the reason catalog. Treat it as a safe-retry hint, not a promise that the next request will fill.

* **Not retryable**: repair the subject, policy, rights, media, or authorization first.
* **Retryable**: follow the declared delay, operation state, and fallback policy.
* **Reconcile first**: read the operation, receipt, provider resource, or external evidence before sending another write.
* **Fallback**: keep source playback safe and do not create a billable event.

## Recovery links

Each error or reason can point to a supported recovery action. A recovery link should open the exact Campaign, Flight, Creative, integration, policy, report, operation, or evidence record. It should not send the operator to a generic home page or require them to search for the subject again.

## Expected result

Operators, support teams, and integrations can name one stable reason, understand whether a retry is safe, and open the exact recovery path. The same reason remains consistent in a decision, API problem, provider diagnostic, report, and evidence package.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.podigee.com/api-reference/readme/error-and-reason-code-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.