> For the complete documentation index, see [llms.txt](https://developers.citrusad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.citrusad.com/partner/reference/error-handling.md).

# Error handling

{% hint style="info" %}
Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view [this page](https://help.citrusad.com/retail-media-interface/partner/partner-api-overview/error-handling) in the new Partner APIs space of our documentation.
{% endhint %}

Epsilon Retail Media Partner APIs follow a structured and consistent error handling approach. This ensures that error responses are predictable, easy to parse, and helpful for debugging.

## Error response structure

When an error occurs, the API returns:

* A standard HTTP status code.
* A structured JSON body with a code, message, and optional details field.
* A list of field-level violations (if applicable), allowing clients to fix multiple issues in one go.

## Basic strategies for handling errors

When you encounter an error, follow these steps:

1. **Read the error message carefully** - The error response provides specific information about what went wrong and which field caused the issue.
2. **Review the endpoint page** - If you're unsure how to proceed, review the specific page for the endpoint you are using.
3. **Contact Support** - If you continue to experience issues, you can raise a case in our Support Portal. Please provide:
   * The exact API call you are making.
   * The specific retailer and team.
   * The specific entity you are creating/updating.
   * The complete error response you are seeing.

This information will ensure our team can assist you efficiently and effectively.

### Single violation example

```json
{
  "code": 3,
  "message": "Invalid argument(s) for product campaign creation",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "maxBid",
          "description": "[maxBid] must be greater or equal [minBid]"
        }
      ]
    }
  ]
}
```

### Multiple violations example

```json
{
  "code": 3,
  "message": "Invalid argument(s) for product campaign update",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "strategy.fixedTenancy.catalogCosts",
          "description": "all catalog cost percentages for fixed tenancy must sum to 100%"
        },
        {
          "field": "strategy.fixedTenancy.catalogCosts",
          "description": "fixed tenancy catalog cost [...] is duplicated in the list"
        }
      ]
    }
  ]
}
```

## Standard HTTP status codes

| HTTP Status Code          | Meaning                       | When it occurs                                  |
| ------------------------- | ----------------------------- | ----------------------------------------------- |
| 200 OK                    | Request succeeded             | Successful API call                             |
| 204 No Content            | Success, no response body     | Successful request with no return payload       |
| 400 Bad Request           | Invalid input                 | Malformed request or validation failure         |
| 401 Unauthorized          | Missing or invalid token      | Token not provided or expired                   |
| 403 Forbidden             | Access denied                 | Token valid but lacks permission                |
| 404 Not Found             | Resource not found            | Invalid endpoint or resource ID                 |
| 409 Conflict              | Duplicate or conflicting data | Resource already exists or violates constraints |
| 429 Too Many Requests     | Rate limit exceeded           | Too many requests in a short time               |
| 500 Internal Server Error | Server-side issue             | Unexpected error on the server                  |
| 503 Service Unavailable   | Temporary outage              | Service is down or under maintenance            |

## gRPC to HTTP error code mapping

| gRPC Code | gRPC Name            | HTTP Code | HTTP Name             |
| --------- | -------------------- | --------- | --------------------- |
| 0         | OK                   | 200       | OK                    |
| 1         | CANCELLED            | 499       | Client Closed Request |
| 2         | UNKNOWN              | 500       | Internal Server Error |
| 3         | INVALID\_ARGUMENT    | 400       | Bad Request           |
| 4         | DEADLINE\_EXCEEDED   | 504       | Gateway Timeout       |
| 5         | NOT\_FOUND           | 404       | Not Found             |
| 6         | ALREADY\_EXISTS      | 409       | Conflict              |
| 7         | PERMISSION\_DENIED   | 403       | Forbidden             |
| 8         | RESOURCE\_EXHAUSTED  | 429       | Too Many Requests     |
| 9         | FAILED\_PRECONDITION | 400       | Bad Request           |
| 10        | ABORTED              | 409       | Conflict              |
| 11        | OUT\_OF\_RANGE       | 400       | Bad Request           |
| 12        | UNIMPLEMENTED        | 501       | Not Implemented       |
| 13        | INTERNAL             | 500       | Internal Server Error |
| 14        | UNAVAILABLE          | 503       | Service Unavailable   |
| 15        | DATA\_LOSS           | 500       | Internal Server Error |
| 16        | UNAUTHENTICATED      | 401       | Unauthorized          |