Skip to main content

​
Error Handling

The Blinksale API uses conventional HTTP response codes to indicate the success or failure of an API request. Here’s a guide to understanding and handling errors in the Blinksale API.

​
HTTP Status Codes

CodeDescription
200 OKThe request was successful
201 CreatedResource was successfully created
400 Bad RequestThe request was invalid or could not be processed
401 UnauthorizedAuthentication failed or token is invalid
403 ForbiddenThe authenticated user doesn’t have permission to access the requested resource
404 Not FoundThe requested resource does not exist
422 Unprocessable EntityValidation errors occurred
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorSomething went wrong on the server

​
Error Response Format

All error responses from the API follow a consistent structure: 
{
  "success": false,
  "message": "A descriptive error message",
  "errors": {
    // Validation errors or additional details (if applicable)
  }
}
For validation errors (422 status code), the errors object will contain field-specific error messages: 
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "email": [
      "The email must be a valid email address."
    ]
  }
}

​
Common Error Types

​
Authentication Errors

If your API token is invalid or expired, you’ll receive a 401 Unauthorized response: 
{
  "success": false,
  "message": "Unauthenticated."
}

​
Permission Errors

If you attempt to access or modify a resource you don’t have permission for, you’ll receive a 403 Forbidden response: 
{
  "success": false,
  "message": "You do not have permission to access this resource."
}

​
Resource Not Found

When requesting a resource that doesn’t exist, you’ll get a 404 Not Found response: 
{
  "success": false,
  "message": "Resource not found."
}

​
Validation Errors

If your request contains invalid data, you’ll receive a 422 Unprocessable Entity response with specific validation errors: 
{
  "success": false,
  "message": "Validation error",
  "errors": {
    "client_id": [
      "The selected client id is invalid."
    ],
    "line_items": [
      "At least one line item is required."
    ]
  }
}

​
Rate Limiting Errors

If you exceed the API rate limits, you’ll receive a 429 Too Many Requests response: 
{
  "success": false,
  "message": "Too many requests. Please try again after {seconds} seconds."
}

​
Best Practices for Error Handling

When working with the Blinksale API, consider these best practices for handling errors:
  1. Check the HTTP status code first to determine the general category of the error.
  2. Parse the error message for more specific information about what went wrong.
  3. Handle validation errors by checking the errors object and addressing each field with issues.
  4. Implement exponential backoff for rate limiting errors to automatically retry after a waiting period.
  5. Log detailed error information in your application to help troubleshoot issues.
  6. Display user-friendly error messages to end-users rather than raw API error responses.

​
Debugging Tips

If you’re encountering errors when working with the API:
  1. Double-check your request parameters against the API documentation.
  2. Verify your authentication token is valid and properly formatted.
  3. Check organization access to ensure you have permission for the operation.
  4. Review your rate limit usage in the response headers.
  5. Contact support if you’re encountering unexpected server errors.