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

Code	Description
`200 OK`	The request was successful
`201 Created`	Resource was successfully created
`400 Bad Request`	The request was invalid or could not be processed
`401 Unauthorized`	Authentication failed or token is invalid
`403 Forbidden`	The authenticated user doesn’t have permission to access the requested resource
`404 Not Found`	The requested resource does not exist
`422 Unprocessable Entity`	Validation errors occurred
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Something 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:

Check the HTTP status code first to determine the general category of the error.
Parse the error message for more specific information about what went wrong.
Handle validation errors by checking the errors object and addressing each field with issues.
Implement exponential backoff for rate limiting errors to automatically retry after a waiting period.
Log detailed error information in your application to help troubleshoot issues.
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:

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

Getting Started

API Reference

Error Handling

Error Handling

HTTP Status Codes

Error Response Format

Common Error Types

Authentication Errors

Permission Errors

Resource Not Found

Validation Errors

Rate Limiting Errors

Best Practices for Error Handling

Debugging Tips

​Error Handling

​HTTP Status Codes

​Error Response Format

​Common Error Types

​Authentication Errors

​Permission Errors

​Resource Not Found

​Validation Errors

​Rate Limiting Errors

​Best Practices for Error Handling

​Debugging Tips

Error Handling

HTTP Status Codes

Error Response Format

Common Error Types

Authentication Errors

Permission Errors

Resource Not Found

Validation Errors

Rate Limiting Errors

Best Practices for Error Handling

Debugging Tips