Error Codes

Error Response Format

Every error response has the same shape, regardless of HTTP status code.

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of what went wrong.",
    "details": []  // Optional array. Present on validation errors.
  }
}

400 Bad Request

The request body is not valid JSON, is empty, or is missing top-level required fields. This fires before schema validation, so it typically means the payload could not be parsed at all.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request body must be valid JSON. Check for trailing commas or unquoted keys."
  }
}

400 Bad Request — Schema Error

The schema definition contains invalid field types, references to undefined tables, or invalid count values.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "SCHEMA_ERROR",
    "message": "Schema validation failed. Check field types, table references, and count values."
  }
}

400 Bad Request — Dependency Cycle

The schema contains circular foreign-key references between tables that cannot be resolved.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "DEPENDENCY_CYCLE",
    "message": "Circular dependency detected between tables."
  }
}

401 Unauthorized

The API key is missing, malformed, expired, or revoked. Check that you are sending a valid key in the Authorization or x-api-key header.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is missing or invalid. Include a valid key in the Authorization header."
  }
}

403 Forbidden

Your API key is valid but your plan does not include the requested feature. Upgrade your plan to access the feature.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "code": "FEATURE_REQUIRES_UPGRADE",
    "message": "Your plan does not include access to the schema detection endpoint. Upgrade to Pro or above."
  }
}

404 Not Found

The requested resource does not exist. This typically means the ID in the URL path is invalid or the resource has been deleted.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found. Check the ID and try again."
  }
}

413 Payload Too Large

The request body exceeds the maximum allowed size of 1 MB. This typically happens when sending very large schema definitions or long prompts.

HTTP/1.1 413 Payload Too Large
Content-Type: application/json

{
  "error": {
    "code": "PAYLOAD_TOO_LARGE",
    "message": "Request body exceeds the 1 MB limit. Reduce the number of table definitions or use a template instead."
  }
}

422 Unprocessable Entity

The JSON is well-formed but the content fails validation. This covers schema errors (invalid field types, missing required fields, circular references) and prompt conversion failures.

Schema Validation Error

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Schema validation failed. See details for specific issues.",
    "details": [
      {
        "field": "tables[0].fields[2].type",
        "message": "Unknown field type \"emial\"",
        "suggestion": "Did you mean \"email\"?"
      },
      {
        "field": "tables[1].fields[0].params.table",
        "message": "Referenced table \"users\" is not defined in the schema."
      }
    ]
  }
}

Prompt Conversion Error

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "PROMPT_CONVERSION_FAILED",
    "message": "Could not convert prompt to a valid schema. Try being more specific about the tables and columns you need."
  }
}

429 Too Many Requests

You have exceeded your daily record limit or per-minute request limit. For per-minute limits, the response includes a Retry-After header indicating how many seconds to wait.

Per-Request Limit Exceeded

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Per-request limit exceeded. Maximum 10,000 records per request for pro tier."
  }
}

Daily Limit Exceeded

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-04-01T00:00:00.000Z

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily record limit exceeded. Your plan allows 1,000 records per day. Resets at 2026-04-01T00:00:00Z."
  }
}

Per-Minute Limit Exceeded

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 42

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Per-minute request limit exceeded. Your plan allows 10 requests per minute."
  }
}

500 Internal Server Error

An unexpected error occurred on the MockHero server. These are rare and are automatically reported to our engineering team. If the error persists, include the X-Request-Id header value when contacting support.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json
X-Request-Id: req_8a3f2c1d7e9b

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Our team has been notified. If this persists, contact support@mockhero.dev with request ID req_8a3f2c1d7e9b."
  }
}

Quick Reference