Error Handling

Understanding how to handle errors is crucial for building robust applications with the Roozna API. This guide will walk you through the structure of error responses and provide best practices for error handling.

Error response structure

When an error occurs, the Roozna API will return an HTTP status code in the 4xx or 5xx range, along with a JSON response body containing more details about the error.

Error object

Name
code
Type
string
Description
A unique error code that identifies the type of error.
Name
message
Type
string
Description
A human-readable description of the error.
Name
details
Type
object
Description
Additional information about the error, when available.

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid or cannot be served.",
    "details": {
      "field": "q",
      "issue": "The search query must not be empty."
    }
  }
}

Common error codes

Here are some common error codes you might encounter when using the Roozna API:

Name
invalid_request
Description
The request was malformed or missing required parameters.
Name
authentication_error
Description
The API key provided was invalid or missing.
Name
authorization_error
Description
The API key doesn't have permission to perform the requested action.
Name
rate_limit_exceeded
Description
The request was rejected due to rate limiting.
Name
not_found
Description
The requested resource was not found.
Name
internal_server_error
Description
An unexpected error occurred on our servers.

Handling errors in your application

Here are some best practices for handling errors in your application:

1. Check the HTTP status code

Always check the HTTP status code of the response. Status codes in the 4xx range indicate client errors, while 5xx codes indicate server errors.

2. Parse the error response

If an error occurs, parse the JSON error response to get more details about what went wrong.

3. Implement retry logic

For transient errors (like rate limiting or temporary server issues), implement a retry mechanism with exponential backoff.

4. Log errors

Log errors on your end for debugging and monitoring purposes. Be careful not to log sensitive information.

5. Provide user-friendly messages

Translate API error messages into user-friendly messages in your application's UI.

Error Handling Example

import axios from 'axios'

async function makeApiRequest() {
  try {
    const response = await axios.get('https://api.roozna.com/v1/search', {
      headers: { 'X-API-Key': 'your_api_key' },
      params: { q: 'tech startups' }
    })
    return response.data
  } catch (error) {
    if (error.response) {
      // The request was made and the server responded with a status code
      // that falls out of the range of 2xx
      console.error('Error response:', error.response.data)
      console.error('Status code:', error.response.status)
      // The request was made and the server responded with a status code
      // that falls out of the range of 2xx
      console.error('Error response:', error.response.data)
      console.error('Status code:', error.response.status)
    } else if (error.request) {
      // The request was made but no response was received
      // `error.request` is an instance of XMLHttpRequest in the browser and an instance of
      // http.ClientRequest in node.js
      console.error('Error request:', error.request)
    } else {
      // Something happened in setting up the request that triggered an Error
      console.error('Error:', error.message)
    }
    console.error('Config:', error.config)
  }
}

Best practices

When implementing pagination in your application, consider these best practices:

Use appropriate page sizes: Choose a limit that balances between reducing the number of API calls and not overwhelming your application with too much data at once.
Handle rate limits: Be mindful of your API rate limits when making multiple paginated requests in quick succession.
Implement infinite scrolling: For a smooth user experience, consider implementing infinite scrolling in your frontend, fetching the next page of results as the user scrolls.
Cache results: If appropriate for your use case, consider caching paginated results to reduce API calls and improve performance.
Handle errors gracefully: Ensure your application can handle scenarios where the API might return an error or an unexpected response format.

Conclusion

Proper use of pagination is crucial for efficiently working with large datasets in the Roozna API. By following this guide and implementing the best practices, you can create applications that handle large volumes of business data smoothly and efficiently.

Explore the Search API documentation