Errors

When a request fails, 3Commas API returns an error object with a relevant HTTP response code and additional information to help identify and resolve the issue.

HTTP Status Codes

Errors generally return a 4xx response code:

4XXMalformed requests (issue is on the sender's side).

401Authentication failed. Possible causes: invalid or expired API key, invalid request signature, or request from a non-whitelisted IP address.

403Access denied. Two possible causes: (1) the API key does not have the required permission enabled (e.g. BOTS_READ) — check the key's permission settings in your 3Commas account; (2) the operation is not allowed for this resource in its current state (e.g. deal cannot be cancelled or active subscription is required).

429Request rate limit exceeded.

418IP auto-banned for continuing to send requests after receiving 429 codes.

5XXInternal errors (issue is on 3Commas's side).

504Gateway timeout, indicating the API couldn’t get a timely response.

Success responses return a 2xx status code.

Attributes

errorstringrequired

Specific error codes and messages defined in another document.

error_descriptionstring

Localized, extended description of the error.

error_attributesstring

Lists fields that did not pass validation.

Error Object

When an error occurs, the API returns an error object instead of a data object or array.

Error responses have the following payload format:

{
  "error": "record_invalid",
  "error_description": "Invalid parameters",
  "error_attributes": {
    "api_key": ["is too short (minimum is 5 characters)"],
    "secret": ["is too short (minimum is 5 characters)"],
    "name": ["is too short (minimum is 2 characters)"]
  }
}