In addition to the already existing INTERNAL_COMMAND_ERROR, our API now has the ability to return a new error code: USER_COMMAND_ERROR. This makes it possible to better distinguish whether an error was caused by incorrect input from the user, or by an internal Transloadit hiccup. This improvement enables you to quickly identify and resolve problems tied to the specific instructions provided, ensuring a smoother experience overall.

Despite our best efforts, not every transcoding operation will finish successfully. In these cases, the Assemblies error out and are marked as failed. Typically, failures stem from one of three reasons:

  • The provided file is malformed or corrupt, for example an image file that is missing the last few bytes.
  • The provided instructions contain errors, for example not supplying a password for an encrypted PDF document.
  • The provided file and instructions are correct, but an internal hiccup caused the operation to fail.

In the past, in all of those cases, the Assembly would end with the error status INTERNAL_COMMAND_ERROR. However, this status makes it hard for our users – and for us as service operators – to distinguish between errors caused by malformed files or instructions and those caused by internal errors. Such a distinction is important for our users to determine which errors they can address on their own, while it allows us to focus on fixing internal problems as quickly as possible.

What will change?

From now on, errors that are caused by malformed files or erroneous instructions will result in the Assembly failing with the new USER_COMMAND_ERROR status. This indicates that an issue arose that can be fixed by the users themselves, for example by correcting the Assembly Instructions.

Assemblies that fail due to Transloadit-internal hiccups will still be marked with the INTERNAL_COMMAND_ERROR status, allowing us to investigate and resolve the problem as soon as possible.

What does this mean for users?

Most users don't have to do anything regarding their integration. You only have to act if your integration code with Transloadit checks for the INTERNAL_COMMAND_ERROR status, for example for logging or starting retries. In these cases, it is also advisable to consider the new USER_COMMAND_ERROR status.

As always, our support team is here to assist you with any questions or concerns. Feel free to reach out, and we'll be happy to guide you through these changes.