Errors · Nexcar API Docs

Format#

Every error uses the same JSON envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "case_id is not a valid UUID",
    "details": { "field": "case_id" }
  }
}

code is stable: your system must branch on it.
message is human-readable and may change (do not parse it).
details is optional and specific to the error.

Common codes#

4xx — client errors#

HTTP	`code`	Meaning	Suggested action
`400`	`MISSING_PARAMETER`	A required field is missing	Review the request body
`400`	`VALIDATION_ERROR`	A field has an invalid format	Check `details.field`
`400`	`DUPLICATE_INTERNAL_ID`	A case already exists for that `internal_id`	Reuse the `case_id` returned in `details`
`401`	`UNAUTHORIZED`	Missing or expired credentials	Refresh your token or check your API key
`401`	`INVALID_CREDENTIALS`	Invalid credentials	Make sure you are using the correct key for the environment
`403`	`FORBIDDEN`	No permission on the resource	Contact support to review your access
`404`	`RESOURCE_NOT_FOUND`	Case or document does not exist	Verify the ID or whether it was soft-deleted
`409`	`CONFLICT`	The resource is in a state incompatible with the operation	Read the current state and retry
`413`	`PAYLOAD_TOO_LARGE`	File > 20 MB	Reduce the file size and retry
`415`	`UNSUPPORTED_MEDIA_TYPE`	MIME not supported	Use a MIME from the catalog
`422`	`INVALID_STATUS`	The `status` value is not part of your catalog	Use a value from the configured catalog
`429`	`RATE_LIMITED`	Rate limit exceeded	Apply backoff and retry

5xx — server errors#

HTTP	`code`	Meaning
`500`	`INTERNAL_ERROR`	Unexpected error on Nexcar's side
`502`	`UPSTREAM_ERROR`	An external service failed (OCR, storage)
`503`	`SERVICE_UNAVAILABLE`	Maintenance in progress

For 5xx, retry with exponential backoff. If it persists for more than 5 minutes, email support@nexcar.mx with the request_id from the response headers.