How should I handle API errors?

The API returns standard HTTP status codes with JSON error bodies:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "band_gap_min must be a positive number",
    "details": { "field": "band_gap_min", "value": -1 }
  }
}

Common Error Codes

| HTTP Status | Error Code | Meaning | |——————-|—————-|————-| | 400 | VALIDATION_ERROR | Invalid parameter value | | 401 | UNAUTHORIZED | Missing or invalid auth token | | 404 | NOT_FOUND | Material or resource not found | | 429 | RATE_LIMITED | Too many requests | | 500 | INTERNAL_ERROR | Server error (please report) |

Best Practices

• Check the HTTP status code before parsing the response body
• For 429 errors, read the Retry-After header and wait before retrying
• For 500 errors, retry with exponential backoff (max 3 retries)
• Log the full error response for debugging