Errors

The Sevalla API uses standard HTTP status codes and returns a consistent JSON error object when something goes wrong.

Error object

Every error response has this shape:

{
  "message": "Unauthorized",
  "status": 401,
  "data": {
    "code": "err-abc-123",
    "message": "If you need assistance, please contact support."
  }
}

Field	Type	Description
`message`	string	Short description of the error.
`status`	integer	HTTP status code.
`data.code`	string	Error tracking identifier. Include this when contacting support.
`data.message`	string	Additional context or instructions for resolving the error.

The data field may not be present on all error responses. Always check for it before accessing nested fields.

HTTP status codes

Code	Meaning
`200`	Success. The request completed and returned data.
`201`	Created. A new resource was created.
`204`	No content. The request succeeded but there’s nothing to return (common for deletes).
`400`	Bad request. The request body or parameters are invalid.
`401`	Unauthorized. Missing or invalid API key.
`403`	Forbidden. The API key doesn’t have permission for this action.
`404`	Not found. The resource doesn’t exist or you don’t have access to it.
`422`	Unprocessable entity. The request was well-formed but failed validation.
`429`	Too many requests. You’re being rate limited.
`500`	Internal server error. Something went wrong on our end.

Handling errors

Check the status code

Use the HTTP status code to determine the category of error. 4xx means something is wrong with your request. 5xx means something went wrong on our side.

Read the message

The message field tells you what went wrong. The data.message field, when present, gives you specific guidance on how to fix it.

Save the error code

If the response includes data.code, save it. Support can use this to look up exactly what happened.

Don’t retry 4xx errors without changing the request. They will keep failing. Retry 5xx errors with exponential backoff.

Getting Started

Projects

Applications

Pipelines

Databases

Static Sites

Object Storage

Load Balancers

Global Environment Variables

API Keys

Webhooks

Usage Alerts

Docker Registries

Users

Resources

Device Authorization

Error object

HTTP status codes

Handling errors

​Error object

​HTTP status codes

​Handling errors

Error object

HTTP status codes

Handling errors