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

# Error handling

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          |


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.citrusad.com/retail-media-interface/partner/partner-api-overview/error-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.