Error handling

You need to handle errors properly in case of an unexpected response from our API.

As seen in the Authentication & format page, to make sure a request was successful, we need to check the property status, which is always present in every response.

When status is False, the response will contain 2 additional properties:

  • error_type : the identifier of the error; refer to our Error type section below
  • error_message a verbose string describing the error

Error types



Your wallet will never be debited if an error occurs during a request, no matter the reason.



We suggest configuring error handling for the INSUFFICIENT_FUNDS error type, to be warned that you are out of wallet funds.

  • General error_type with their description:
INSUFFICIENT_FUNDSYou do not have enough funds to perform this request
INVALID_REQUEST_TYPEThis endpoint is invalid, and the product doesn't exist
NO_KEYNo API key specified
INACTIVE_API_KEYThis API key was deactivated
SYSTEM_ERROR, UNHANDLED_EXCEPTION, SYSTEM_UNAVAILABLEAn error occurred on our side; the support team was notified. Please retry later
RATE_LIMITED_1_MINUTE, RATE_LIMITED_5_SECONDSYou have performed too many requests in 1 minute or in 5 seconds. Please refer to our Rate limiting section below
INACTIVE_API_ACCESSYou deactivated your full API access from the dashboard
INVALID_REQUEST_TIMEOUTThe specified timeout is not valid. Please use one of those values: minimal, normal, extensive
INVALID_REQUEST_PHONEThe specified phone is not valid. Please submit a valid phone number in international format, for example: 14567890000 or 33600000000
INVALID_REQUEST_EMAILThe specified email is not valid. Please submit a valid email address format
INVALID_PARAMETERThe parameters you submitted are not the ones we expect for this endpoint. Review your request body
INVALID_LABELThe custom label you entered is over 30 characters
  • Team-only error_type with their description:
INACTIVE_TEAM_USERYour team administrator deactivated your account
DAILY_CHECK_LIMITYou reached the maximum daily spending allowed by your team Role
INVALID_PERMISSIONYour team role doesn't have permission to use the API

Rate limiting

We have two rate-limiting systems in place that apply to any Defastra account:

  • 60 requests per minute -> error_type RATE_LIMITED_60_PER_MINUTE if reached
  • 2 requests per second -> error_type RATE_LIMITED_2_PER_SECOND if reached



Rate limiting can be increased by simply contacting us.

By imposing a rate limit, we keep tight control over our architecture.