Troubleshoot API‘s errors

Summary

Learn how to diagnose Box+Dice API errors by understanding endpoint behaviour, request patterns, and configuration checks required for third‑party integrations.

This article covers:

• About Box+Dice API behaviour
• Basic Troubleshooting
• Understand API error codes
• Review authentication
• How pagination works
• Manage rate limits
• Check IP restrictions
• API concepts and definitions

About Box+Dice API behaviour

The Box+Dice API allows third‑party systems to retrieve and update CRM data securely. It is designed to support integrations such as website platforms, marketing tools, and custom applications. 
Understanding how the API handles authentication, pagination, time‑based queries, and rate limits helps developers diagnose issues faster and ensure stable data synchronisation. 
Developers and support teams use these features to connect external platforms, manage data flows efficiently, and troubleshoot errors during API requests. 

Basic Troubleshooting

Before troubleshooting, confirm that the third party is using the correct API documentation.

• Review the list of available APIs
• Confirm the third party is referencing the correct endpoints and expected behaviour
• Ask third‑party developers key troubleshooting questions

To help diagnose API integration issues: 

• Which API is enabled?
• Are they using the correct documentation and endpoints?
• Do they have the correct client URL?
• What error message are they getting?
• What cURL are they using?
• Have they gone to the last page of the endpoint?

Understand API error codes

These are common API status codes you might encounter so you can identify what the system is reporting

• 200 Success - the request was processed successfully, and the response contains the requested resources
• 201 Created - the request was processed successfully, and a new record was created
• 204 No Content - no resources are matching the request
• 401 Unauthorized - missing or invalid Authorization request header
• 403 Forbidden - IP address restriction is enabled
• 404 Not Found - a record requested by ID does not exist
• 429 Too Many Requests - used to limit the request rate

Review authentication

Users can generate an API key for any office group in CRM. Any website's back-end can then use the key's token to authenticate against the Box+Dice API.
The API uses the Api-Key authentication scheme. The token has to be included in the Authorization request header with every request:

Authorization: Api-Key token=b3c7623c3ad30d34fec6226f90914b0af125dc06

How pagination works

Timestamps paginate all API endpoints that return an array of records. The optimal use of the API endpoints to fetch all records is as follows:

• First, send a request with no arguments. This will return a batch of records with the oldest timestamps. It will also return the following attribute containing a URL for the next request. This URL contains an after parameter that tells the API which record was returned last in the last response
• Next, send a request to the new URL. One of two things will happen:
  • If there are new or updated records, API will respond with 200 Success status code, return another batch of records and provide new next URL
  • If there are no new or updated records, the API will respond with a 204 No Content status code and an empty response body. This means the client has received the most recent data. In this case, the client should wait for a reasonable amount of time and retry sending a request to the same URL

Manage rate limits

All paginated API endpoints enforce rate limits. All these endpoints return a Retry-After response code containing several seconds the client should wait before making another request. The value defaults to

• 10 seconds for responses with status code 200 OK,
• 1 minute for responses with status code 204 No Content.

If a rate limit is exceeded, the server will respond with status code 429, "Too Many Requests." The response will include a Retry-After header, which contains the number of seconds to wait before sending another request. The limits are subject to change, so the API clients should observe and respect the Retry-After response header.

The rate limits are applied to each paginated endpoint individually, not to the API as a whole.

Check IP restrictions

If a request returns a 403 Forbidden with the message 'IP address not allowed', check IP control settings.

• Open the CRM and navigate to the API configuration
• Confirm whether the IP is listed under Restricted List
• If the restriction is applied in a third party’s backend, confirm they have the correct IP whitelisted
• For troubleshooting, you may temporarily disable the IP address restriction toggle

API concepts and definitions

Understand key terms and their definitions to support developers during troubleshooting.

• What is a cURL?
  • A cURL is a command-line tool and library that transfers data to or from a server
• What does that mean to the API?
  • In Postman, when you enter all the details for the command you want to execute, the code snippet button <> is on the right-hand side. In here you will find the cURL. It contains all the information you need to confirm whether the command is correct

• What does the reference after the attribute in the documentation mean?
  • These are data types
    • Number - returns a number (listing id)
    • Boolean - returns a true/false (is current?)
    • String - returns a word (sale, leased, auction)
    • Date - returns a date in the format of YYYY-MM-DD (inspections, auctions)
    • Time - returns the time in the format of T16:23:59.000+02:00 (inspections, auctions)
    • Array of Object - returns a list (categories)