Error codes

Every error Render returns — with the specific field at fault and exactly how to fix it.

Render never returns a generic error. Every error response includes a machine-readable code, a human-readable message, the field at fault (where applicable), and a doc_url linking here.

Error response shape

JSON

{
  "error": {
    "code":    "invalid_utr",
    "message": "UTR must be exactly 10 digits.",
    "field":   "company.utr",
    "doc_url": "https://docs.render.my/errors#invalid_utr"
  }
}

field is set to null for errors that are not tied to a specific request parameter (e.g. authentication errors, HMRC rejections).

Authentication errors

Code	HTTP	Description
`authentication_required`	401	The Authorization header is missing or the Bearer token is empty.
`invalid_api_key`	401	The API key format is not recognised. Keys must start with sk_sandbox_ or sk_live_.
`sandbox_key_in_live`	403	A sandbox key (sk_sandbox_) was used to make a request that routes to HMRC live. Switch to a live key or use test_mode: true.

Validation errors (422)

Validation errors are returned before anything reaches HMRC. Fix the field indicated by field and retry.

Code	HTTP	Description
`invalid_utr`	422	UTR must be exactly 10 digits, numeric only.
`invalid_period_date`	422	Period start or end date is not a valid ISO 8601 date, or period end is before period start.
`invalid_monetary_value`	422	A monetary field must be an integer (pence). Fractional values and strings are not accepted.
`invalid_accounting_standard`	422	Must be exactly "frs102" or "frs105".
`ixbrl_date_mismatch`	422	The period end date in your iXBRL document does not match period.end. HMRC error 1606 would result.
`ixbrl_malformed`	422	The iXBRL document is not well-formed XHTML or fails arelle validation. HMRC error 1607 would result.
`schema_validation_failed`	422	The generated GovTalk XML envelope failed HMRC XSD schema validation. Detailed XPath location is provided in message.
`idempotency_conflict`	409	The Idempotency-Key header matches a previous request but the request body differs. Use a new key for a different request.
`filing_not_found`	404	No filing with the given ID exists for your account.

HMRC errors

These errors originate from HMRC's GovTalk response. The message includes the original HMRC error text.

If you receive hmrc_rejected in sandbox, it indicates a schema or BVR rule violation that our pre-submission validation did not catch. Please contact support with your filing ID.

Code	HTTP	Description
`hmrc_rejected`	502	HMRC returned a GovTalk error response. The original HMRC error text is in message. Common causes: wrong UTR, unsupported taxonomy version, IRmark mismatch.
`hmrc_unavailable`	503	HMRC's GovTalk endpoint did not respond within the timeout period. Render will not have submitted the filing. Retry with the same Idempotency-Key.

Server errors (5xx)

Code	HTTP	Description
`irmark_calculation_failed`	500	An internal error occurred while computing the IRmark signature. This is always a Render bug — please report it with your request ID.

Handling errors in code

Python

from render.errors import (
    RenderError,
    ValidationError,
    AuthenticationError,
    NotFoundError,
)

try:
    filing = client.filings.create(...)

except ValidationError as e:
    # Fix the specific field and retry
    print(e.code)     # "invalid_utr"
    print(e.field)    # "company.utr"
    print(e.message)  # "UTR must be exactly 10 digits."

except AuthenticationError:
    # Check your API key
    print("Invalid or missing API key")

except NotFoundError:
    print("Filing not found")

except RenderError as e:
    # Catch-all for unexpected errors
    print(f"Unexpected error: {e.code}")

Node.js

import { ValidationError, AuthenticationError, RenderError } from 'tunnel';

try {
  const filing = await client.filings.create({ ... });
} catch (err) {
  if (err instanceof ValidationError) {
    console.log(err.code);    // "invalid_utr"
    console.log(err.field);   // "company.utr"
    console.log(err.message); // "UTR must be exactly 10 digits."
  } else if (err instanceof AuthenticationError) {
    console.log('Check your API key');
  } else if (err instanceof RenderError) {
    console.log(`Unexpected error: ${err.code}`);
  }
}