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

# Error handling

> File-level vs row-level errors, what details you get, and how to fix and re-upload safely.

When an upload cannot be fully processed, Acclaim returns errors so you can see **what failed** and **where**. Errors may apply to the whole file or to individual rows.

## Error types

### File-level errors

These stop the upload from being processed at all. Examples:

* Unsupported file type
* Missing or invalid header row
* Template does not match the file
* Required columns missing after mapping
* Unreadable or malformed file

When a file-level error occurs, **reject the whole upload**, fix the file or template, and upload again.

### Row-level errors

These affect **one row** while other rows can still succeed. Examples:

* Missing required field
* Invalid amount format
* Unsupported currency for the method
* Invalid bank details
* Payout method mismatch
* Country-specific validation failure

## Error reporting

You should receive enough detail to correct data quickly, typically including:

* Upload or file identifier
* **Row number**
* **Field** name (when applicable)
* Error code or type
* Human-readable message

Exact fields depend on the Console or API surface you use—align support training with what your team actually sees.

## Common file-level errors

| Error                    | What it means                             |
| ------------------------ | ----------------------------------------- |
| Unsupported file type    | Not a supported CSV or XLSX               |
| Missing headers          | No valid header row                       |
| Invalid template         | Template does not match columns or method |
| Missing required columns | One or more required columns are absent   |

## Common row-level errors

| Error                               | What it means                              |
| ----------------------------------- | ------------------------------------------ |
| Missing required field              | Required value blank or absent             |
| Invalid format                      | Value does not match expected pattern      |
| Invalid payout method data          | Method-specific fields missing or wrong    |
| Country-specific validation failure | Fails country or corridor rules            |
| Invalid conditional field set       | Wrong combination for payee type or method |

## Example row-level errors

| Row | Field                 | Error                                           |
| --- | --------------------- | ----------------------------------------------- |
| 4   | `bank_account.clabe`  | Must be exactly 18 digits                       |
| 7   | `currency`            | Unsupported currency for selected payout method |
| 12  | `payee.business_name` | Required when `payee.type` is `business`        |

## Partial success

Uploads often finish with **partial success**: many rows succeed, a few fail. In that case:

* Valid rows continue to payout creation.
* Failed rows are listed with errors.
* You fix only the failed rows (or the file structure) and re-upload as needed.

<Warning>
  Do not re-upload successful rows unless your process explicitly requires it—duplicates can create duplicate payouts depending on your safeguards.
</Warning>

## Correcting errors

<Steps>
  <Step>
    Open the error report for the upload and note **row** and **field** for each failure.
  </Step>

  <Step>
    Fix the spreadsheet or export (or adjust the template if mapping was wrong).
  </Step>

  <Step>
    Upload a **new** file containing only corrected rows, or a full file if that is your standard control.
  </Step>
</Steps>

<Tip>
  Keep templates stable and validate files internally before upload during high-stakes windows (month-end, regulatory deadlines).
</Tip>

## Related resources

* [File uploads overview](./overview)
* [File format](./file-format)
* [Template configuration](./template-configuration)
* [Validation rules](./validation)
* [Processing flow](./processing)
* [Examples](./examples)