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

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.