Skip to main content

API - Recommendations: Response Codes & Troubleshooting

David S
Updated

When using the Recommendations endpoints on Surfe, your request may return different response codes depending on the outcome. Here's a simple guide to what they mean and what to do next.

Create or Update ICP

Endpoint: POST /v2/recommendations/icp

API Docs →

201 – Created

  • What it means: Your ICP was successfully created or updated.

  • Next steps: Use the returned id and your externalUserId when calling the Fetch Recommendations endpoint.

400 – Invalid Request

  • What it means: Some required information is missing or incorrectly formatted.

  • Next steps: Double-check your request body. Make sure all filter values are valid — use the Get Filters endpoint to check accepted values for industries, departments and seniorities.

401 – Unauthorized

  • What it means: Your API key is missing or invalid.

  • Next steps: Confirm you've included a valid API key in the request headers.

404 – Not Found

  • What it means: The requested record cannot be found.

  • Next steps: Check that your externalUserId is correct.

500 – Internal Server Error

  • What it means: Something went wrong on our side.

  • Next steps: Wait a moment and try again. If the issue continues, reach out to the support team via Intercom.

Fetch Recommendations

Endpoint: POST /v2/recommendations/fetch

API Docs →

200 – Success

  • What it means: Your request worked and recommendations have been returned.

  • Next steps: Review the returned companies and people. Use the pagination.hasMore field to check if there are more results available.

400 – Invalid Request

  • What it means: Some required information is missing or incorrectly formatted.

  • Next steps: Make sure your request body includes the required pagination object with from and to values.

401 – Unauthorized

  • What it means: Your API key is missing or invalid.

  • Next steps: Confirm you've included a valid API key in the request headers.

403 – Forbidden

  • What it means: The request cannot be handled because it would either exceed your daily quota or there are not enough credits available.

  • Next steps: Check your credit balance via your Surfe dashboard or the Get Credits endpoint. If you've hit your daily quota, wait until midnight for it to reset. If you need higher limits or are unsure what's causing this, contact our support team via Intercom and we'll help you out.

500 – Internal Server Error

  • What it means: Something went wrong on our side.

  • Next steps: Wait a moment and try again. If the issue continues, reach out to the support team via Intercom.

Get ICP Filters

Endpoint: GET /v2/recommendations/icp

API Docs →

200 – Success

  • What it means: Your request worked and your saved ICP filters have been returned.

  • Next steps: Review the returned filters and use them when fetching recommendations.

400 – Invalid Request

  • What it means: The request is not properly formatted.

  • Next steps: Check your query parameters and make sure they are correctly formatted.

401 – Unauthorized

  • What it means: Your API key is missing or invalid.

  • Next steps: Verify that your API key is included and active.

500 – Internal Server Error

  • What it means: Something went wrong on our side.

  • Next steps: Try again shortly. If the problem persists, contact support via Intercom.

Need Help?

If you're ever unsure about an error or how to fix it, our team is here to help. Reach out to the support team via Intercom.

 

Additional Resources

Comments

0 comments

Please sign in to leave a comment.