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 #
- 2xx
-
Success. Your request was processed.
- 4xx
-
Client error. The request was invalid in some way — bad token, missing permission, malformed payload, exceeded rate limit.
- 5xx
-
Server error. Something went wrong on Depfloy’s side. Safe to retry after a short backoff.
Common status codes #
- 200 Success
-
The request succeeded; the response body contains the resource.
- 201 Created
-
A new resource was created. The response body usually echoes the new resource’s ID.
- 400 Bad Request
-
The request was malformed (invalid JSON, missing required headers).
- 401 Unauthenticated
-
The Bearer token is missing, malformed, or revoked.
- 403 Forbidden
-
The Bearer token is valid but does not have the permission this endpoint requires.
- 404 Not Found
-
The resource doesn’t exist, or your token doesn’t have access to it.
- 422 Unprocessable Entity
-
Validation failed. The response includes which fields failed and why.
- 429 Too Many Requests
-
Rate limit exceeded (60 requests per minute per token). Back off and retry.
- 500 Server Error
-
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:
{
"status": "error",
"message": "Server not found."
}Validation errors (422) include the field-level details:
{
"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."
}