3. Rate Limiting, Status Codes & Responses

Rate Limits

Endpoint	Rate Limit
`/import`	10 requests/second
`/import-many`	5 requests/second
`/evaluate`	5 requests/second
`/evaluate-many`	3 requests/second
`/import-shipment-volumes`	10 requests/second
`/import-many-projects-shipment-volumes`	10 requests/second

Response Codes

Code	Status	Description
`200`	OK	The request was successful.
`400`	Bad Request	The payload is invalid (e.g., malformed JSON or schema violation).
`401`	Unauthorized	Missing or invalid API credentials.
`403`	Forbidden	You do not have permission to access this resource.
`429`	Too Many Requests	You have exceeded the rate limit. Retry with exponential backoff.
`500`	Internal Error	An unexpected error occurred on Recyda's servers.
`502`	Gateway Error	Invalid response from the upstream server or gateway issue.

⚠️ A 200 status code indicates the API gateway received and parsed your request. However, you must check the response body for a backend_error_alias object. If this object is present, the operation failed on the backend (e.g., database constraint, internal logic error) despite the HTTP 200 status.

Standard Response Samples

1. Successful Operation

A standard success response returns the requested data and a null error object.

{
"data": {
"status": "success",
"message": "Operation completed successfully.",
"id": "SKU-1001"
},
"backend_error_alias": null
}

2. Backend Error Status (400 Bad Request / Schema Validation)

If the JSON payload violates the OPS schema, the backend returns a descriptive error indicating the exact path of the failure. Note: The specific object path and message in the response will vary depending on which attribute is incorrectly formatted.

{ "data": null, "backend_error_alias": { "code": "SCHEMA_VALIDATION_FAILED", "message": "The provided payload violates the OPS schema constraints.", "details": "consumerSalesUnitInput.packagingUnits.0.packagingUnit.components.0.attributes.rigidity: consumerSalesUnitInput.packagingUnits.0.packagingUnit.components.0.attributes.rigidity must be one of the following: \"RIGID\", \"FLEXIBLE\"" } }

3. Gateway Error Status (502 Bad Gateway)

In the rare event of a gateway or upstream issue, you may receive a wrapped HTML response indicating a 502 Bad Gateway.

{
"error_backend_alias": {
"http_status_code": 502,
"http_body": "<html>\r\n<head><title>502 Bad Gateway</title></head>\r\n<body>\r\n<center><h1>502 Bad Gateway</h1></center>\r\n<hr><center>nginx/1.28.2</center>\r\n</body>\r\n</html>\r\n",
"http_body_encoding": "text/html"
}
}