Errors¶

A failed request answers with an HTTP status and a problem document (RFC 9457), as application/problem+json:

{
  "type": "https://api.touch2build.com/problems/validation_error",
  "title": "The request is not valid",
  "status": 400,
  "code": "validation_error",
  "instance": "/v1/projects/8f4c.../tasks",
  "requestId": "3b1f6a0e-9c2d-4f57-a1e8-0d6b2f9c7e41",
  "errors": [
    { "field": "name", "code": "required", "message": "\"name\" must not be blank" },
    { "field": "position.x", "code": "out_of_range", "message": "\"position.x\" must be greater than or equal to 0" }
  ]
}

• Branch on code: it never changes once published. title, detail and message are for people and may be reworded.
• detail, when present, explains this particular occurrence.
• requestId identifies the request in our logs: quote it when you contact support.
• errors lists every invalid value at once, for validation_error. field is the path of the value (position.x, tags[2], or the name of a query parameter or header), and its code is one of required, too_long, too_short, out_of_range, invalid_format, invalid_value or unknown_field.

401 and insufficient_scope responses also carry a WWW-Authenticate header (RFC 6750); for insufficient_scope, it names the scope required.

Codes¶

400 Bad Request¶

validation_error

A value of the body, of the query or of a header is missing, malformed or out of range. See errors.

invalid_request

The request cannot be read, for example a body that is not valid JSON.

invalid_cursor

The cursor was altered, or was produced by a request with other filters. Start again without a cursor.

invalid_sort

This list cannot be sorted by that field.

401 Unauthorized¶

unauthorized

The Authorization header is missing, or the key or token is not valid: mistyped, expired or revoked. Check the key; do not retry with the same one.

403 Forbidden¶

forbidden

You may not do this: the project is not one of yours, your role in the project does not allow it, or the feature is turned off for the project.

insufficient_scope

The key or token does not allow this request, typically a write with a read-only key. Use a key with Read and write access.

license_violation

Your license does not allow this, for example a project or plan over the limit of the free plan. See Licence et abonnement.

404, 405, 406, 410¶

not_found

The resource does not exist, or the path is wrong.

method_not_allowed

The resource exists but does not accept this HTTP method.

not_acceptable

The Accept header asks for a format the resource cannot produce.

gone

The resource was deleted.

409 Conflict¶

conflict

The request conflicts with the current state of the resource, for example removing yourself from a project.

tag_in_use

The tag is still on tasks. Remove it from them first.

folder_not_empty

The folder still holds plans, geo maps or folders.

plan_processing

The plan was just uploaded and is still being processed. Retry a few seconds later.

plan_failed

The file of the plan could not be processed. Upload another PDF with PUT /v1/plans/{planId}/content.

idempotency_in_progress

A request with the same Idempotency-Key is still running. Retry when it is done.

413, 415, 422¶

payload_too_large

The body exceeds 50 MB, or the image is too large.

unsupported_media_type

The Content-Type is not accepted here, or the file does not match it (a plan that is not a PDF).

idempotency_key_reused

The Idempotency-Key was already used for a different request. Use a new key for each resource.

429 Too Many Requests¶

rate_limited

Too many requests in a short time. Wait for the number of seconds in Retry-After, then retry.

5xx¶

internal_error

An unexpected error on our side. Retry later; if it persists, write to support@touch2build.com with the requestId.

upstream_error

A service the API depends on failed, for example while rendering a plan. Retry later.

service_unavailable

The API is temporarily unavailable. Retry later, waiting longer each time.

Retrying¶