Error handling

Epsilon Retail Media's documentation is now centralized with our knowledgebase!

For up to date guides, please view this page in the new Partner APIs space of our documentation.

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

{
  "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

{
  "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