API Errors

All API errors return a JSON body with an error message and a machine-readable code.

{
  "error": "Entity not found.",
  "code": "not_found"
}

HTTP status codes

Status	Description
`400`	Bad request. The request body is invalid or missing required fields.
`401`	Unauthorized. The API key is missing or invalid.
`403`	Forbidden. The API key does not have permission for this operation.
`404`	Not found. The requested resource does not exist.
`409`	Conflict. The resource already exists or the idempotency key was already used with different parameters.
`422`	Unprocessable. The request was well-formed but could not be completed (e.g., insufficient balance, Entity not verified).
`429`	Rate limited. Too many requests. Retry after the duration specified in the `Retry-After` header.
`500`	Internal server error. Something went wrong on our end.

Common error codes

Code	Status	Description
`unauthorized`	401	Missing or invalid API key.
`forbidden`	403	API key does not have access to this resource.
`not_found`	404	The requested resource was not found.
`validation_error`	400	One or more fields in the request body are invalid.
`insufficient_balance`	422	The source Account does not have enough funds.
`entity_not_verified`	422	The Entity has not completed KYC/KYB. Required for IBANs and wire transfers.
`duplicate_resource`	409	A resource with these attributes already exists.
`idempotency_conflict`	409	The idempotency key was already used with different request parameters.
`rate_limited`	429	Too many requests. Back off and retry.
`transfer_failed`	422	The transfer could not be completed. Check the transfer details for more information.

Rate limits

The API allows up to 100 requests per second per API key. If you exceed this limit, you will receive a 429 response with a Retry-After header indicating how many seconds to wait before retrying.

Protocol error codes

The following error codes apply to on-chain protocol operations. These are returned when an Instruction execution fails at the contract level.

Code	Type	Description
1201	Terminal	User account is not delegated to the OtimDelegate contract
1202	Terminal	Signature verification failed for the provided instruction
1203	Terminal	Action cannot be executed due to contract-level restrictions
1204	Retryable	Action execution failed on-chain, may succeed with retry
1205	Terminal	Instruction has already been deactivated and cannot be executed
1206	Terminal	Instruction has already been deactivated in DeactivateInstructionAction

Code	Type	Description
1301	Terminal	Invalid or malformed arguments provided for transfer action
1302	Terminal	SafeERC20 transfer operation failed due to token contract issues
1303	Retryable	Insufficient fee token balance to cover execution costs
1304	Retryable	Insufficient native token balance for the transfer amount

Code	Type	Description
1305	Terminal	Invalid or malformed arguments provided for ERC20 transfer action
1306	Terminal	SafeERC20 transfer operation failed due to token contract issues
1307	Retryable	Insufficient fee token balance to cover execution costs
1308	Retryable	Insufficient ERC20 token balance for the transfer amount

Code	Type	Description
1309	Terminal	Invalid or malformed arguments provided for refuel action
1310	Terminal	SafeERC20 transfer operation failed due to token contract issues
1311	Retryable	Insufficient fee token balance to cover execution costs
1313	Retryable	Insufficient native token balance for the refuel amount

Code	Type	Description
1314	Terminal	Invalid or malformed arguments provided for ERC20 refuel action
1315	Terminal	SafeERC20 transfer operation failed due to token contract issues
1316	Retryable	Insufficient fee token balance to cover execution costs
1318	Retryable	Insufficient ERC20 token balance for the refuel amount

Code	Type	Description
1319	Terminal	Invalid or malformed arguments provided for UniswapV3 swap action
1320	Terminal	UniswapV3 pool does not exist for the specified token pair and fee tier
1321	Terminal	Unexpected invalid tick data encountered during pool validation
1322	Terminal	SafeERC20 transfer operation failed due to token contract issues
1323	Retryable	Insufficient fee token balance to cover execution costs
1324	Retryable	Insufficient input token balance for the swap amount
1328	Retryable	UniswapV3 swap received too little output tokens

Code	Type	Description
1340	Retryable	Insufficient fee token balance to cover execution costs
1341	Terminal	Invalid or malformed arguments provided for deactivate instruction action
1342	Terminal	SafeERC20 transfer operation failed due to token contract issues

Code	Type	Description
1343	Terminal	Invalid or malformed arguments provided for sweep CCTP action
1344	Terminal	CCTP token is not supported for the specified operation
1345	Retryable	Insufficient fee token balance to cover execution costs
1346	Terminal	SafeERC20 transfer operation failed due to token contract issues

Code	Type	Description
1347	Terminal	Invalid or malformed arguments provided for transfer CCTP action
1348	Retryable	Insufficient token balance for the CCTP transfer amount
1349	Terminal	CCTP token is not supported for the specified operation
1350	Retryable	Insufficient fee token balance to cover execution costs
1351	Terminal	SafeERC20 transfer operation failed due to token contract issues

Code	Type	Description
1352	Terminal	Invalid or malformed arguments provided for sweep action
1353	Retryable	Insufficient fee token balance to cover execution costs
1354	Terminal	SafeERC20 transfer operation failed due to token contract issues

Code	Type	Description
1355	Terminal	Invalid or malformed arguments provided for sweep ERC20 action
1356	Retryable	Insufficient fee token balance to cover execution costs
1357	Terminal	SafeERC20 transfer operation failed due to token contract issues

Code	Type	Description
1358	Terminal	Invalid or malformed arguments provided for sweep UniswapV3 action
1359	Terminal	UniswapV3 pool does not exist for the specified token pair and fee tier
1360	Terminal	Unexpected invalid tick data encountered during pool validation
1361	Terminal	SafeERC20 transfer operation failed due to token contract issues
1362	Retryable	Insufficient fee token balance to cover execution costs

Core Objects

API

SDK

Protocol

HTTP status codes

Common error codes

Rate limits

Protocol error codes

​HTTP status codes

​Common error codes

​Rate limits

​Protocol error codes

HTTP status codes

Common error codes

Rate limits

Protocol error codes