Skip to main content
All APIs return errors in a consistent envelope format.

​
Error Format

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

​
Error Codes

StatusCodeDescription
400BAD_REQUESTThe request body or parameters are invalid
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENValid key but insufficient permissions
404NOT_FOUNDResource does not exist
409CONFLICTResource already exists or state conflict
422VALIDATION_ERRORRequest body failed validation
429RATE_LIMITEDToo many requests — see Rate Limits
500INTERNAL_ERRORUnexpected server error

​
Validation Errors

422 VALIDATION_ERROR responses include field-level details: 
{
  "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