Skip to main content
v1.0GuidesGuidesAPI ReferenceAPI Reference

Status Codes / Errors

When interacting with Sona's API endpoints, it is important to understand the status codes that might be generated.

To find a status code in this documentation:

  1. Go to the reference documentation for an endpoint such as Profile360.
  2. By default, the Response section of the reference docs shows an example response with a 200 status. To view other status codes, click the Response samples buttons (e.g., 200, 404), then select a status code.
  3. The status you select will appear in the response section.

You do not need to supply an API key to review the Sona-generated example response or other status codes. Check out the API Reference to explore endpoints and test responses.

Common HTTP Status Codes​

Success Responses​

200 OK​

The request was successful. The response body contains the requested data.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "success",
  "data": {
    // Response data
  }
}

Client Error Responses​

400 Bad Request​

The request was malformed or missing required parameters.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "error",
  "data": {
    "message": "Please provide at least one filter."
  }
}

Common causes:

  • Missing required parameters
  • Invalid parameter format
  • Invalid email or domain format

401 Unauthorized​

The API key is missing or invalid.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "error",
  "data": {
    "message": "Unauthorized. Please provide a valid API key."
  }
}

Solution: Ensure you're including a valid x-api-key header in your request. You can create or manage API keys at Access Keys.

403 Forbidden​

You do not have permission to access this resource, or you've exceeded your credit limit.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "error",
  "data": {
    "message": "Insufficient credits. Please upgrade your plan."
  }
}

Common causes:

  • Insufficient Sona credits
  • Plan limitations
  • Account access restrictions

Solution: Check your Billing Overview to review your credit usage and consider upgrading your plan.

404 Not Found​

The requested resource was not found in the database.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "error",
  "data": {
    "message": "Profile not found"
  }
}

Common causes:

  • No data available for the provided email or domain
  • Invalid or non-existent identifier
  • Resource doesn't exist in Sona's database

Note: A 404 response may still consume credits if the API performed a lookup attempt.

429 Too Many Requests​

You've exceeded the rate limit for API requests.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "error",
  "data": {
    "message": "Rate limit exceeded. Please try again later."
  }
}

Solution: Implement exponential backoff and retry logic in your application. Consider using bulk endpoints to process multiple records efficiently.

Server Error Responses​

500 Internal Server Error​

An unexpected error occurred on the server.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "error",
  "data": {
    "message": "An internal server error occurred."
  }
}

Solution: If this error persists, please contact Sona Support with the request details and timestamp.

503 Service Unavailable​

The API is temporarily unavailable, usually due to maintenance.

Example Response:

{
  "version": "2.0.0",
  "php": "8.3.25",
  "status": "error",
  "data": {
    "message": "Service temporarily unavailable. Please try again later."
  }
}

Solution: Wait a few moments and retry your request. If the issue persists, check the Sona Status Page for updates.

Error Handling Best Practices​

When integrating with the Sona API, follow these best practices for handling errors:

  1. Always check the status field - The response includes a status field that will be either "success" or "error".

  2. Parse error messages - The data.message field contains human-readable error descriptions.

  3. Implement retry logic - For transient errors (429, 500, 503), implement exponential backoff:

    async function retryWithBackoff(fn, maxRetries = 3) {
      for (let i = 0; i < maxRetries; i++) {
        try {
          return await fn();
        } catch (error) {
          if (i === maxRetries - 1) throw error;
          await new Promise((resolve) =>
            setTimeout(resolve, Math.pow(2, i) * 1000)
          );
        }
      }
    }

  4. Monitor your credits - Track credit usage to avoid 403 errors due to insufficient credits.

  5. Log errors appropriately - Include request details (without sensitive data) in your logs for debugging.

  6. Handle 404 gracefully - Not all emails/domains will have data available. Design your application to handle missing data elegantly.

Response Structure​

All Sona API responses follow a consistent structure:

{
  "version": "2.0.0", // API version
  "php": "8.3.25", // Server PHP version
  "status": "success", // "success" or "error"
  "data": {
    // Response data or error details
    // ... endpoint-specific data
  }
}

For successful requests, the data object contains the enriched information. For errors, it contains a message field with error details.

Need Help?​

If you encounter persistent errors or need assistance:

Last updated on by Sona