Skip to main content
The API uses standard HTTP status codes and returns structured JSON error bodies.

​
Error format

Every error response has this shape: 
{
  "error": {
    "code": "not_found",
    "message": "No item found with ID itm_abc123.",
    "field": null
  }
}
FieldTypeDescription
codestringMachine-readable error code for programmatic handling.
messagestringHuman-readable description of what went wrong.
fieldstring | nullThe request field that caused the error, when applicable.

​
HTTP status codes

StatusMeaningWhen you’ll see it
200OKSuccessful read or update.
201CreatedSuccessfully created a new resource.
204No ContentSuccessful delete.
400Bad RequestInvalid request body, missing required field, or malformed parameter.
401UnauthorizedMissing or invalid API token.
403ForbiddenValid token but insufficient permissions (e.g., no Pro subscription).
404Not FoundThe requested resource doesn’t exist or doesn’t belong to your account.
409ConflictResource already exists (e.g., duplicate tag name).
422Unprocessable EntityRequest is well-formed but semantically invalid (e.g., invalid URL).
429Too Many RequestsRate limit exceeded. See rate limits.
500Internal Server ErrorSomething went wrong on our end. Retry with backoff.

​
Error codes

CodeStatusDescription
bad_request400Generic invalid request.
validation_error400A specific field failed validation. Check field.
unauthorized401Invalid or missing API token.
forbidden403Pro subscription required, or resource not accessible.
not_found404Resource not found or not owned by you.
conflict409Resource already exists.
unprocessable422Request is syntactically valid but can’t be processed.
rate_limited429Too many requests. Check Retry-After header.
internal_error500Server error. Retry with exponential backoff.

​
Validation errors

When a specific field is invalid, the field property tells you which one: 
{
  "error": {
    "code": "validation_error",
    "message": "URL must start with http:// or https://.",
    "field": "url"
  }
}

​
Handling errors

response = requests.post(url, headers=headers, json=data)

if response.status_code >= 400:
    error = response.json()["error"]
    if error["code"] == "rate_limited":
        retry_after = int(response.headers["Retry-After"])
        time.sleep(retry_after)
    elif error["code"] == "validation_error":
        print(f"Fix field '{error['field']}': {error['message']}")
    else:
        print(f"Error: {error['message']}")