​

Introduction

The following list of HTTP status codes is returned by Piloterr. Each status code indicates the outcome of an API call and suggests a potential resolution for errors.

​

Soft Fail Mode

The soft_fail=true parameter can be added to any API request to handle 404 errors with a 200 status code. This feature is particularly useful when:

• You want to handle errors in your application logic without relying on HTTP status codes
• You’re working with systems that treat non-200 status codes as fatal errors (e.g make.com)
• You need to maintain consistent error handling across different integrations

Usage Example

# Standard request
GET https://api.piloterr.com/v2/company?query=piloterr&soft_fail=true&X_api_key=YOUR_API_KEY

# Response
STATUS_CODE: 200
{
    "error": "Not Found",
}

Important Note: Even though the request returns a 200 status, the original error is:

• Included in the response body (error)
• Tracked in your dashboard with the actual error code (e.g., 404)
• Billed according to standard error code billing rules

​

Note on 404 Errors

While most 404 errors are billed, there are specific exceptions for search-related endpoints. The following endpoints are NOT billed when returning a 404 error:

• /api/v2/company - Company search endpoint
• /api/v2/company/suggest - Company name suggestions
• /api/v2/company/social - Social media search
• /api/v2/linkedin/company/info - LinkedIn company information

This policy ensures that you’re not charged for legitimate “no results found” scenarios during search operations. All other endpoints follow the standard billing rules for 404 errors.

​

Additional Notes

• 400 Bad Request: This status indicates that the server cannot process the request due to a client error (e.g., malformed request syntax or invalid parameters).
• 401 Unauthorized: Typically returned when an invalid API key is used. Make sure your API key is active and not expired.
• 402 Payment Required: Occurs if there are outstanding invoices. Settle any open invoices to continue using the API.
• 403 Forbidden: Indicates that the user does not have permission to access the requested resource.
• 429 Too Many Requests: This status indicates that the client has sent too many requests in a given amount of time (rate limiting).
• 500 Internal Server Error: This is a generic error message for unexpected server issues. Check logs for more detailed information.