---
agentTools:
  projectIndex: https://docs.defastra.com/llms.txt
---

# Error handling & rate limiting

[block:api-header]
{
  "title": "Error handling"
}
[/block]

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

As seen in the [Authentication & format page](https://docs.defastra.com/reference/authentication), 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](https://docs.defastra.com/reference/error-handling#error-types)
* `error_message` a verbose string describing the error

[block:api-header]
{
  "title": "Error types"
}
[/block]

[block:callout]
{
  "type": "info",
  "title": "Important",
  "body": "Your wallet will never be debited if an error occurs during a request, no matter the reason."
}
[/block]

[block:callout]
{
  "type": "warning",
  "title": "Important",
  "body": "We suggest configuring error handling for the ```INSUFFICIENT_FUNDS``` error type, to be warned that you are out of wallet funds."
}
[/block]

* General `error_type` with their description:

[block:parameters]
{
  "data": {
    "h-0": "error_type",
    "h-1": "description",
    "0-0": "```INSUFFICIENT_FUNDS```",
    "0-1": "You do not have enough funds to perform this request",
    "1-1": "This endpoint is invalid, and the product doesn't exist",
    "1-0": "```INVALID_REQUEST_TYPE```",
    "2-1": "Invalid API key",
    "2-0": "```INVALID_API_KEY```",
    "3-0": "```NO_KEY```",
    "3-1": "No API key specified",
    "4-0": "```INACTIVE_API_KEY```",
    "4-1": "This API key was deactivated",
    "5-0": "```SYSTEM_ERROR```, ```UNHANDLED_EXCEPTION```, ```SYSTEM_UNAVAILABLE```",
    "5-1": "An error occurred on our side; the support team was notified. Please retry later",
    "6-0": "```RATE_LIMITED_1_MINUTE```, ```RATE_LIMITED_5_SECONDS```",
    "6-1": "You have performed too many requests in 1 minute or in 5 seconds. Please refer to our **Rate limiting** section below",
    "7-0": "```INACTIVE_API_ACCESS```",
    "7-1": "You deactivated your full API access from the dashboard",
    "8-0": "```INVALID_REQUEST_TIMEOUT```",
    "9-0": "```INVALID_REQUEST_PHONE```",
    "10-0": "```INVALID_REQUEST_EMAIL```",
    "11-0": "```INVALID_PARAMETER```",
    "11-1": "The parameters you submitted are not the ones we expect for this endpoint. Review your request body",
    "8-1": "The specified timeout is not valid. Please use one of those values: minimal, normal, extensive",
    "9-1": "The specified phone is not valid. Please submit a valid phone number in international format, for example: 14567890000 or 33600000000",
    "10-1": "The specified email is not valid. Please submit a valid email address format",
    "12-0": "```INVALID_LABEL```",
    "12-1": "The custom label you entered is over 30 characters"
  },
  "cols": 2,
  "rows": 13
}
[/block]

* Team-only `error_type` with their description:

[block:parameters]
{
  "data": {
    "h-0": "error_type",
    "h-1": "description",
    "0-0": "```INACTIVE_TEAM_USER```",
    "0-1": "Your team administrator deactivated your account",
    "1-0": "```DAILY_CHECK_LIMIT```",
    "1-1": "You reached the maximum daily spending allowed by your team Role",
    "2-0": "```INVALID_PERMISSION```",
    "2-1": "Your team role doesn't have permission to use the API"
  },
  "cols": 2,
  "rows": 3
}
[/block]

[block:api-header]
{
  "title": "Rate limiting"
}
[/block]

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

[block:callout]
{
  "type": "success",
  "title": "Note",
  "body": "Rate limiting can be increased by simply [contacting us](https://defastra.com/contact-us)."
}
[/block]

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