> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# on_codes

> Contract, placement, related fields and source examples for this Nika YAML field.

[Language reference](https://docs.nika.sh/reference/language/overview.md) / `on_codes`

## Meaning and placement

### retry

Retry ONLY on these canonical `NIKA-<NS>-<NNN>` codes · absent, the engine retries anything transient. Codes, never HTTP status numbers · the retry-side mirror of `on_error.on_codes`.

| Property | Declaration |
| - | - |
| Requirement | Optional in this object |
| Schema location | `/$defs/retry/properties/on_codes` |
| type | `"array"` |

**In the same object:** [backoff\_max\_ms](https://docs.nika.sh/reference/language/words/backoff_max_ms.md) · [backoff\_ms](https://docs.nika.sh/reference/language/words/backoff_ms.md) · [backoff\_strategy](https://docs.nika.sh/reference/language/words/backoff_strategy.md) · [jitter](https://docs.nika.sh/reference/language/words/jitter.md) · [max\_attempts](https://docs.nika.sh/reference/language/words/max_attempts.md)

[Schema source (use the pointer above)](https://github.com/supernovae-st/nika-spec/blob/4e259e5b8012fcdf92f094142a52dfef24099b85/schemas/workflow.schema.json)

### onError

Optional catch-side filter (mirror of retry.on\_codes · same regex) · the action applies ONLY when the final error code is listed · unlisted codes fall through to the default fail (spec/05-errors.md §Fields).

| Property | Declaration |
| - | - |
| Requirement | Optional in this object |
| Schema location | `/$defs/onError/properties/on_codes` |
| type | `"array"` |

**In the same object:** [recover](https://docs.nika.sh/reference/language/words/recover.md) · [skip](https://docs.nika.sh/reference/language/words/skip.md)

[Schema source (use the pointer above)](https://github.com/supernovae-st/nika-spec/blob/4e259e5b8012fcdf92f094142a52dfef24099b85/schemas/workflow.schema.json)

## In a source template

Excerpt from `templates/api-upload-and-create.nika`, source lines 92–99. This is a fragment, not a runnable workflow.

```yaml illustration theme={"system"}
      # answering 401). The literal is shaped EXACTLY like what the jq above
      # projects, so `outputs.result` has the same shape on both paths. Delete
      # the block once the key is wired, so an unset key is loud as well.
      on_codes: [NIKA-VAR-001]
      recover: { id: "rehearsal-0001", url: "https://app.example.com/items/rehearsal-0001" }

outputs:
  result: ${{ tasks.create.output }}   # SLOT: the callable contract
```

### Templates containing this field

| Template | Source |
| - | - |
| `templates/api-upload-and-create.nika` | [Line 95](https://github.com/supernovae-st/nika-spec/blob/4e259e5b8012fcdf92f094142a52dfef24099b85/templates/api-upload-and-create.nika#L95) |
| `templates/chain.nika` | [Line 59](https://github.com/supernovae-st/nika-spec/blob/4e259e5b8012fcdf92f094142a52dfef24099b85/templates/chain.nika#L59) |
| `templates/etl-state.nika` | [Line 81](https://github.com/supernovae-st/nika-spec/blob/4e259e5b8012fcdf92f094142a52dfef24099b85/templates/etl-state.nika#L81) |
| `templates/human-gated-ship.nika` | [Line 105](https://github.com/supernovae-st/nika-spec/blob/4e259e5b8012fcdf92f094142a52dfef24099b85/templates/human-gated-ship.nika#L105) |
| `templates/recover-optional-file.nika` | [Line 36](https://github.com/supernovae-st/nika-spec/blob/4e259e5b8012fcdf92f094142a52dfef24099b85/templates/recover-optional-file.nika#L36) |

These are literal key occurrences in the source files, not an execution or conformance claim. [How to instantiate a template](https://docs.nika.sh/guides/templates.md).

## Contract and implementation

This page projects the named specification revision. Check [released engine status](https://docs.nika.sh/reference/status.md) and [the validation workflow](https://docs.nika.sh/guides/agent-authoring.md) before running a file. An optional field is not evidence that every engine supports every value.

Canonical identity: `language:word:on_codes`. Spec revision: [`4e259e5b8012`](https://github.com/supernovae-st/nika-spec/tree/4e259e5b8012fcdf92f094142a52dfef24099b85).

[How documentation stays connected](https://docs.nika.sh/reference/knowledge-system.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.