DocsErrors and limits
Docs/Developer API·Last reviewed

Errors and limits

Every failed call gets the same error envelope. This page lists each error code with what to do about it, then the rate limits and the photo limits you will meet first.

Envelope

A failure answers with a JSON body holding one error object. The same id is also in the X-Request-Id response header.

{
  "error": {
    "code": "validation_failed",
    "message": "The request has invalid fields.",
    "details": [
      {
        "field": "priority",
        "code": "invalid_value",
        "message": "This value is not allowed."
      }
    ],
    "request_id": "req_01H00000000000000000000000"
  }
}

Branch on code, never on message. Messages may be reworded, and codes may not alter, only be added. details has one entry for each field with a problem and is left out when there are none. Quote the request_id, which starts req_, when you contact support.

A 400 is a request the server could not read. A 422 is a request it could read but refuses: invalid fields, an expired updated_since window, a rejected upload or a reused Idempotency-Key.

Access codes

The retry column says whether the same request can succeed later. Backoff means waiting a little longer after each failure, with some randomness.

CodeHTTPMeaningRetry
unauthorized401The key is missing, malformed, unknown, expired or revoked.No, fix the request
api_not_enabled403The API is not switched on for this company.No, fix the request
forbidden403This key is not allowed to do that.No, fix the request
credential_in_query400The key was sent in the query string. Use the Authorization header.No, fix the request
rate_limited429Too many requests.Yes, after Retry-After
internal_error500A fault on our side. Quote the request_id.Yes, with backoff

Request codes

CodeHTTPMeaningRetry
invalid_request400The request could not be read.No, fix the request
validation_failed422A field is refused. See details.No, fix the request
sync_window_expired422The walk starts more than 90 days back. Run a full walk.No, fix the request
payload_too_large413The request body is too large.No, fix the request
not_found404No record with that id.No, fix the request
route_not_found404No such endpoint, or the wrong method for it.No, fix the request

Refusals

CodeHTTPMeaningRetry
create_not_available409Defects cannot be opened through the API here. details says why.No, fix the request
action_not_available409The action is not available for this defect right now. details says why.No, fix the request
external_id_conflict409Another defect already has this external id for that system.No, fix the request
precondition_failed412The defect was edited after you read it.No, fix the request

Uploads and repeats

CodeHTTPMeaningRetry
upload_missing409The photo file has not reached upload_url yet.No, fix the request
upload_rejected422The file did not match what was declared, so it was removed.No, fix the request
idempotency_key_reused422This Idempotency-Key was used for a different request.No, fix the request
idempotency_in_progress409A request with this key is still running.Yes, after Retry-After
temporarily_unavailable503Nothing was written. The API could not check the request just now.Yes, after Retry-After

Fixing by a step

Two refusals are fixed by a step, not by waiting. After precondition_failed, read the defect again and send its latest ETag in If-Match. After upload_missing, finish sending the file and confirm the photo again.

Detail codes

A details[].code says why a field or an action was refused. These values are frozen, and more are only added over time. These come with validation_failed.

Detail codeMeaning
requiredThe field is required.
invalid_typeThe field has the wrong type.
invalid_formatThe field is not in the expected format.
invalid_valueThe value is not allowed.
out_of_rangeThe value is outside the allowed range or length.
unknown_fieldThe field is not accepted.

These come with upload_rejected.

Detail codeMeaning
size_mismatchThe file is not the size that was declared.
too_largeThe file is larger than 26,214,400 bytes.
type_mismatchThe file was stored with a different content type.
content_mismatchThe file is not the image format that was declared.

Availability codes

These come with create_not_available.

Detail codeMeaning
fenced_projectRecords on this project are made in IssuesId only, for now.
outbound_orgAnother system numbers this company's records.
aconex_createThe project sends records to the client's own register.
raised_rule_outsideA rule would email someone outside the company.

Action codes

These come with action_not_available.

Detail codeMeaning
issued_to_limit_reachedAt most 11 trades fit on a defect.
upload_limit_reachedToo many uploads from the last 24 hours were never confirmed.
root_cause_requiredThe company needs a root cause before a defect closes, and the API cannot set one yet.

Limits

Each key may make 600 reads and 120 writes a minute. A GET or HEAD is a read and every other method is a write, and the two are counted apart. A company's keys together may make 1,800 reads and 360 writes a minute, so three busy keys fit before they start to crowd each other. Bursts up to the per-minute number are allowed.

Every response to an identified call carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. They describe the limit that binds at that moment, the key's or the company's, and RateLimit-Reset is the whole seconds until it is full again.

Past a limit the answer is 429 rate_limited with Retry-After, the seconds to wait. Wait that long, then send the same request again.

Repeated failed authentication from one address is refused with 429 for a while, so fix a wrong key instead of retrying it. A call to a path the API does not have answers route_not_found and is not counted in a key's usage in Settings > Public API.

Photo limits

A photo is image/jpeg, image/png, image/webp, image/heic or image/heif, from 1 byte to 25 MB (26,214,400 bytes). The file you send must be exactly the size you declared.

The upload link lasts 15 minutes. A confirmed photo is listed with download links that stop working an hour after they are made, so ask again instead of keeping one.

Every endpoint lists the errors it can return in the API reference.

IssuesId