Errors & Rate Limits

When integrating with Rackbeat's APIs, understanding how errors are communicated is crucial for building robust applications. This guide covers the error response patterns you'll encounter and how to handle them effectively. By understanding these error patterns, you can build more resilient integrations that gracefully handle various failure scenarios and provide meaningful feedback to users.

HTTP Status Codes

200 (OK)

This is the most commonly used success status, returned for successful GET requests (retrieving resources), PUT/PATCH requests (updating resources), DELETE operations, and most POST operations that perform actions rather than creating new resources.

201 (Created)

This is specifically used when POST requests successfully create new resources, such as copying a customer invoice (/customer-invoices/{id}/copy), where the response includes the full details of the newly created resource.

206 (Partial Content)

This is extensively used for paginated list endpoints, such as /customer-invoices, /offers, and /orders. These responses include pagination metadata (total, pages, limit, page) along with the requested data subset, allowing clients to efficiently navigate large datasets

422 Unprocessable Entity (Most Common Error Code)

The primary error status code you'll encounter is HTTP 422, used for validation errors and business logic violations. This is the standard response when your request is syntactically correct but contains invalid data.

Example Response

{
  "errors": {
    "customer_id": [
      "The selected Customer is invalid."
    ],
    "lines.0.item_id": [
      "Product needed"
    ],
    "lines.0.variations.0.option_id": [
      "The selected lines.0.variations.0.option_id is invalid."
    ]
  }
}

Common scenarios triggering 422 errors

• Missing required fields
• Invalid foreign key references (e.g., non-existent customer_id)
• Validation rule violations (e.g., invalid email format)
• Business rule violations (e.g., insufficient inventory)

401 Unauthorized

Returned when authentication fails or is missing. Always remember that all API requests require proper authentication headers. Omitting or providing invalid authentication will result in 401 errors.

{
  "errors": {
    "message": "Unauthenticated."
  }
}

404 Not Found

When requesting a resource that doesn't exist.

{
  "errors": {
    "message": "Customer Invoice not found."
  }
}

429 Too Many Requests

When the client has sent too many requests in a given amount of time.

💡

Rackbeat API endpoints enforce a rate limit of 480 requests per minute per account.

500 Internal Server Error

For unexpected server errors.

{
  "errors": {
    "message": "Internal server error"
  }
}

Error Message Structure

Validation Errors (422)

Validation errors use a field-based structure where each field contains an array of error messages:

{
  "errors": {
    "field_name": [
      "First error message for this field",
      "Second error message for this field"
    ],
    "another_field": [
      "Error message for another field"
    ]
  }
}

General Errors

Non-validation errors use a simple message format:

{
  "errors": {
    "message": "Human-readable error description"
  }
}

Notable Characteristics

• No HTTP 204 (No Content) responses: Rackbeat APIs don't typically return 204 No Content. Operations that might typically return 204 instead return 200 with a simple JSON message, maintaining consistency in the response format across all endpoints.
• No HTTP 400 responses: Rackbeat APIs don't typically return 400 Bad Request. Invalid requests usually return 422 instead.
• Consistent structure: All error responses follow the same {"errors": {...}} format.
• Detailed validation: Field-level validation errors include the exact path to the problematic field, including array indices (e.g., lines.0.item_id).
• Connection headers: Error responses include Connection: Close headers to manage connection lifecycle.