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.

Status Code	Is Billed?	Explanation	Resolution
200	Yes	Successful API Call	No action required.
400	No	Bad Request / Inactive API Key / Expired API Key	Verify your parameters and their types. Ensure your API key is active and not expired. Check the detailed error message in the response body for more information.
401	No	Unauthorized / Invalid API Key	Check your API key and ensure it is valid.
402	No	Payment Required / You Have Open Invoices	Settle any outstanding invoices to continue using the API.
403	No	Forbidden / Account Deactivated	Verify your permissions. Contact us if you believe this is a mistake.
404	Yes*	Not Found / URL Not Found	Ensure the endpoint URL is correct. This is billed except for specific endpoints listed below.
429	No	Rate Limit Exceeded	Consider upgrading your current plan or get in touch with our sales team.
500	No	Unexpected Error	Retry the action and check the detailed error message in the response body for more insights.

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.

On this page

Introduction
Soft Fail Mode
Note on 404 Errors
Additional Notes

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.

Status Code	Is Billed?	Explanation	Resolution
200	Yes	Successful API Call	No action required.
400	No	Bad Request / Inactive API Key / Expired API Key	Verify your parameters and their types. Ensure your API key is active and not expired. Check the detailed error message in the response body for more information.
401	No	Unauthorized / Invalid API Key	Check your API key and ensure it is valid.
402	No	Payment Required / You Have Open Invoices	Settle any outstanding invoices to continue using the API.
403	No	Forbidden / Account Deactivated	Verify your permissions. Contact us if you believe this is a mistake.
404	Yes*	Not Found / URL Not Found	Ensure the endpoint URL is correct. This is billed except for specific endpoints listed below.
429	No	Rate Limit Exceeded	Consider upgrading your current plan or get in touch with our sales team.
500	No	Unexpected Error	Retry the action and check the detailed error message in the response body for more insights.

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.

On this page

Introduction
Soft Fail Mode
Note on 404 Errors
Additional Notes

​Introduction

​Soft Fail Mode

​Note on 404 Errors

​Additional Notes

Datasets

​Introduction

​Soft Fail Mode

​Note on 404 Errors

​Additional Notes

Introduction

Soft Fail Mode

Note on 404 Errors

Additional Notes

Introduction

Soft Fail Mode

Note on 404 Errors

Additional Notes