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.

HTTP Status Codes

200 (OK)

201 (Created)

206 (Partial Content)

422 Unprocessable Entity (Most Common Error Code)

401 Unauthorized

404 Not Found

429 Too Many Requests

500 Internal Server Error

Error Message Structure

Validation Errors (422)

General Errors

Notable Characteristics

`200 (OK)`

`201 (Created)`

`206 (Partial Content)`

`422 Unprocessable Entity` (Most Common Error Code)

`401 Unauthorized`

`404 Not Found`

`429 Too Many Requests`

`500 Internal Server Error`