Problems

What every failed request returns, and what each kind of problem means.

When a request fails, our APIs answer with a problem document, sent as application/problem+json. Its type is a link to one of the pages here, so you can open it to read what went wrong and how to fix it.

{
  "type": "https://docs.digitospace.com/problems/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "run_in_progress",
  "detail": "this job is already running; wait for it to finish, then run it again",
  "instance": "/v1/projects/01k5ztq3jb9y2a1m9v2xw8e0ha/jobs/01m3c081d2wj4g63qcr53pa1yh/run",
  "requestId": "01m3c081dbf3j55x7hsa7wc1yj",
  "retryable": false
}

Fields

typestring: A link to the page for this kind of problem. Each kind also has its own status.
titlestring: The name of the kind of problem. The same for every problem of that kind.
statusinteger: The HTTP status, the same as the response’s.
codestring: Exactly what went wrong, such as run_in_progress. Branch on this. A code changes only after it has been deprecated.
detailstring: A sentence for a person about this failure. It may be reworded at any time, so do not branch on it.
instancestring: The path of the request that failed.
requestIdstring: The request’s ID. Quote it when you contact us about a failure.
retryableboolean: Whether the same request could succeed if you send it again later.
resourcestring: The kind of thing that was missing or clashed, such as job. Only on some problems.
issuesarray: Every field that is wrong. Only on Validation failed.

Handle a problem

Branch on code for failures your app can handle, such as a name already in use.
Otherwise, handle the kind of problem by its status.
When retryable is true, send the request again after a short wait.
Log the requestId with every failure you do not handle.

Every problem

Status	Problem	When you get it
400	Invalid request	The request is malformed, so we could not read it.
401	Authentication required	The request did not say who is making it, or we did not accept the credentials it sent.
403	Forbidden	We know who is making the request, but they may not do this.
404	Not found	The thing the request asks for does not exist, or the route itself does not exist.
405	Method not allowed	The route exists, but not for the HTTP method the request used.
409	Conflict	The request clashes with the current state of what it changes.
413	Payload too large	The request body is bigger than we accept.
415	Unsupported media type	The request body is not in a format we accept.
422	Validation failed	We could read the request, but some of its fields break the rules.
500	Internal error	Something went wrong on our side while handling the request.
503	Service unavailable	Something the request depends on is not available right now.

Last updated 26 September 2026