Skip to main content

Error handling

The SDK does not have its own error classes and never retries a request. There are two kinds of errors, and both are thrown (the returned promise rejects):

Validation errors

Before sending a request, each method checks some of its arguments and throws a plain Error when they are invalid. No request is made in this case.

API errors

Requests are made with Axios. When the API answers with an error status (or cannot be reached), the Axios error is thrown as is:
  • error.response.status is the HTTP status.
  • error.response.data.error is the message returned by the API.
  • error.response is undefined when there was no response at all (network error).
See the API introduction for the meaning of each status.
downloadFile asks Axios for binary data, so when it fails error.response.data is a Buffer containing the JSON of the error. Use JSON.parse(error.response.data.toString()) to read the message.

Pitfalls

getApplications() takes no parameters and calls GET /v1/apps without a query string. The API then returns the first page (10 applications) of your personal applications only. Applications of teams and the following pages cannot be requested through the SDK. Check pagination.hasNextPage and call the API directly when you need more.
The SDK builds the URL as /apps/{appId}/upload?path=${path}. When path is omitted, the text undefined is sent and the API extracts the zip into an undefined folder. Always pass path ("/" for the root).
The API rejects anything that is not a zip, and the SDK always names the upload file.zip. A zip is extracted into path, overwriting files with the same name. To send a single file, zip it first.
Even for a single file, the Buffer returned by downloadFile is a zip archive that contains it.
uploadFile and downloadFile insert path in the URL without encoding it. Paths with spaces or with &, #, ? or % may be misread. Encode them yourself with encodeURIComponent.
The signature is app.uploadFile({ file, path }). Passing two positional arguments (app.uploadFile(file, "/path")) fails with File must be a valid Buffer., because the SDK looks for the file and path properties on the first argument.
The data of an Application instance is the response of the request that created the instance. Calling start(), stop(), restart() or update() does not change it.
The API answers with 500 when you start an application that is already running, stop one that is already stopped, or restart one that is not running. Check currentResourceMetrics.online first, or catch the error.
When exposedViaWeb is true the API requires port (and assignedSubdomain on creation). The SDK has no parameter for them, so createApplication and updateApplication fail with 400 in that case. Use the API directly to expose an application to the web.
The API accepts "nodejs", "bun" and "python", but runtimeEnvironment is typed as "nodejs" | "python". The SDK does not check the value at runtime, so in TypeScript you can pass "bun" as any.
A variable with an empty value makes the API answer with 500. In updateApplication, omitting environmentVariables keeps the current variables, while passing [] removes all of them.
The SDK throws when one of them is missing, even if you only want to change another setting. Read the current values from Application.data (name, allocatedMemoryMB, runtimeEnvironment) and send them back. teamId is accepted by the type but ignored.
Unlike the other methods, deleteApplication (and Application.delete) resolves with the complete Axios response. The body is in .data.
The SDK does not wait nor retry. Creating, updating and uploading are limited to 1 request every 3 seconds each, downloads to 20 per minute, and everything to 180 requests per minute. See Limits.
The package is CommonJS. In a .mjs file or a "type": "module" project, import CamposCloudSDK from "@camposcloud/sdk" gives you the module object instead of the class. See Getting started.
Responses are returned without any validation, and the exported types do not describe every field. See Types.