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

# Partial errors

> Learn about partial errors and how to recover when parts of a request fail.

## What are partial errors?

Some endpoints perform multiple API calls to the target system behind a single request. For example, creating a booking proposal with an attachment may require one call to create the booking proposal and a separate call to upload the file.

Partial errors occur when the main operation succeeds, but one or more secondary operations fail. Unlike regular errors that return a 4xx or 5xx status code, partial errors return a successful HTTP status code (2xx) along with details about what went wrong in the `meta.partialErrors` array.

This approach ensures that you don't lose the primary result when a non-critical operation fails. For example:

* You create a booking proposal with an attachment
* The booking proposal is created successfully in the target system
* The file upload fails
* Instead of failing the entire request and losing the created booking proposal, the API returns the booking proposal data along with a partial error indicating the file could not be uploaded

This allows you to handle the failure gracefully - the main entity exists, and you can retry the failed operation separately using a recovery endpoint.

## Response structure

When partial errors occur, they appear in the `meta.partialErrors` array:

```json theme={null}
{
  "data": {
    "id": "12345",
    "number": "INV-001"
  },
  "meta": {
    "partialErrors": [
      {
        "code": "FILE_UPLOAD_FAILED",
        "message": "Attachment invoice.pdf could not be uploaded to the target system."
      }
    ]
  }
}
```

Each partial error contains:

* `code`: A machine-readable identifier for the error type
* `message`: A human-readable description of what went wrong

## Error codes

| Code | Description |
| :- | :- |
| `FILE_UPLOAD_FAILED` | The file attachment could not be uploaded to the target system after the main entity was created. |
| `INCOMPLETE_CREATION` | The entity was created but is incomplete: some request body fields could not be applied. |

> [!NOTE]
>
> Additional error codes may be added in the future. Always check the `meta.partialErrors` array in your responses.

## Handling partial errors

1. Always check if `meta.partialErrors` exists and has items after a successful response
2. Log or store the error details for debugging
3. Use the recovery endpoint documented in each API endpoint to retry the failed operation

> [!NOTE]
>
> Each endpoint documents which integrations support partial errors and the available recovery options.


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