Skip to main content
KennelBooker Developer Platform Developer Portal
API fundamentals

Errors and troubleshooting

Use HTTP status codes for broad handling and the response error code for application-specific decisions.

Error response format

JSON error responses contain a stable machine-readable code, a developer-facing message and a request id that can be supplied when contacting KennelBooker support.

Example error response 
{
  "error": {
    "code": "not_found",
    "message": "The requested booking could not be found.",
    "requestId": "req_01JKB7M4E8J3F9D2R6T1Y5Q0P"
  }
}
Error messages are intended for developers and may change. Build application logic around the HTTP status and error.code, not the message text.

Status and error codes

Endpoint documentation may list additional errors. These are the common responses every integration should be prepared to handle.

Status Error code Meaning Recommended action
400 invalid_request The request is malformed or contains invalid values. Correct the request using the message and validation details.
401 authentication_failed The API key is missing, invalid or no longer active. Send a valid X-Api-Key header for the KennelBooker business.
403 forbidden The authenticated integration cannot perform this action. Check the key's business, access level and requested operation.
404 not_found The requested resource does not exist or is not accessible. Check the resource identifier and the authenticated business.
409 conflict The request conflicts with the current resource state. Refresh the resource, resolve the conflict and retry if appropriate.
429 rate_limit_exceeded The integration has sent too many requests. Wait before retrying and honour the Retry-After header when supplied.
500 internal_error KennelBooker could not complete an otherwise valid request. Retry later. Contact support with the request id if it continues.
503 service_unavailable The API is temporarily unavailable. Retry with exponential backoff and a maximum attempt limit.

Validation errors

When one or more fields are invalid, the response can include a details collection. Display appropriate feedback to the user without exposing the entire raw response.

Validation error 
{
  "error": {
    "code": "invalid_request",
    "message": "One or more values are invalid.",
    "requestId": "req_01JKB7N20W6Q9B8Y4F1X3Z5VT",
    "details": [
      {
        "field": "startDate",
        "code": "required",
        "message": "A start date is required."
      }
    ]
  }
}

Retrying requests safely

Retry only temporary failures such as 429, 500 and 503. Use exponential backoff, add a small random delay and stop after a limited number of attempts.

Attempt 1 Wait approximately 1 second
Attempt 2 Wait approximately 2 seconds
Attempt 3 Wait approximately 4 seconds
Do not automatically retry validation, authentication, permission or not-found errors. The request must be changed first.

Request IDs and support

Record the request id from failed API calls in your integration logs. It allows KennelBooker support to locate the corresponding server-side request without requiring you to disclose customer data or API keys.

Include these details when reporting a problem

  • The request id returned by the API
  • HTTP method and endpoint path
  • Approximate request time including timezone
  • HTTP status and machine-readable error code