Errors

​

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found.",
    "status": 404,
    "details": null
  }
}

​

Error Codes

​

Validation Errors

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input.",
    "status": 422,
    "details": [
      {
        "field": "gtin",
        "message": "GTIN must be 8, 12, 13, or 14 digits."
      }
    ]
  }
}

​

Best Practices

• Check the code field for programmatic error handling, not the message
• Log the full error response for debugging
• Implement retry logic with exponential backoff for 429 and 5xx errors
• Do not retry 4xx errors (except 429) — they indicate a client issue

​

Domain-specific 422 responses

• AB 660 / Date Labels — the Products API returns 422 when product_name, description, net_content, or usage_instructions contains a phrase banned by California AB 660 (e.g. "sell by", "best before", "expires on").