Errors

Use the response status code to determine whether your request succeeded; use the error message for debugging. Most error messages are actionable enough to fix the request without contacting support.

Status code categories

Name
2xx
Description
Success. Your request was processed.
Name
4xx
Description
Client error. The request was invalid in some way — bad token, missing permission, malformed payload, exceeded rate limit.
Name
5xx
Description
Server error. Something went wrong on Depfloy's side. Safe to retry after a short backoff.

Common status codes

Name
200
Type
Success
Description
The request succeeded; the response body contains the resource.
Name
201
Type
Created
Description
A new resource was created. The response body usually echoes the new resource's ID.
Name
400
Type
Bad Request
Description
The request was malformed (invalid JSON, missing required headers).
Name
401
Type
Unauthenticated
Description
The Bearer token is missing, malformed, or revoked.
Name
403
Type
Forbidden
Description
The Bearer token is valid but does not have the permission this endpoint requires.
Name
404
Type
Not Found
Description
The resource doesn't exist, or your token doesn't have access to it.
Name
422
Type
Unprocessable Entity
Description
Validation failed. The response includes which fields failed and why.
Name
429
Type
Too Many Requests
Description
Rate limit exceeded (60 requests per minute per token). Back off and retry.
Name
500
Type
Server Error
Description
Something went wrong on our side. If you see this consistently, contact support with the request ID.

Error response shape

Most errors return a JSON body in this shape:

Generic error

{
  "status": "error",
  "message": "Server not found."
}

Validation errors (422) include the field-level details:

Validation error

{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "domain": ["The domain must be a valid hostname."]
  }
}

Rate-limit errors (429) include retry headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "status": "error",
  "message": "Too many requests."
}