Errors

COALS uses conventional HTTP status codes to indicate success or failure. Error responses always include a JSON body with a machine-readable code and a human-readable message.

Standard Error Format

Most endpoints return structured errors with an error object containing a code and message. The code is a stable string identifier you can match in your code; the message is for humans.

Structure

{
  "success": false,
  "error": {
    "code":    "ERROR_CODE",
    "message": "Human-readable description of what went wrong."
  }
}

Flat error format

Some services (notably older SimCoal endpoints) return a flat string rather than a nested object: "error": "Error message". Your client should handle both shapes.

HTTP Status Codes

Status	Name	Description
200	OK	Request succeeded. Response body contains the result.
400	Bad Request	The request was malformed or missing required parameters.
401	Unauthorized	No API key provided, or the key is invalid or revoked.
403	Forbidden	API key is valid but does not have the required scope for this endpoint.
404	Not Found	The requested resource (job, image, log, etc.) does not exist.
413	Payload Too Large	Uploaded file exceeds the size limit for the endpoint.
422	Unprocessable Entity	Request body was understood but failed validation. Response includes per-field errors.
429	Too Many Requests	Rate limit exceeded. Check the `Retry-After` header before retrying.
500	Internal Server Error	An unexpected error occurred on our end. If this persists, contact support.

Validation Errors — 422

When a request fails validation, the response body contains a details object mapping each invalid field to an array of error strings. This lets you surface precise feedback to your users.

Request

POST /api/v1/simcoal/send

{
  "to":      "not-a-phone-number",
  "message": ""
}

Response — 422

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request failed validation.",
    "details": {
      "to": [
        "The to field must be a valid E.164 phone number."
      ],
      "message": [
        "The message field is required."
      ]
    }
  }
}

Common Error Codes

UNAUTHORIZED 401 API key is missing or invalid.

FORBIDDEN 403 API key lacks the required scope for this operation.

NOT_FOUND 404 The requested resource was not found.

VALIDATION_ERROR 422 One or more fields failed validation.

PAYLOAD_TOO_LARGE 413 Uploaded file exceeds the allowed size.

RATE_LIMIT_EXCEEDED 429 Too many requests. Honor the Retry-After header.

INTERNAL_ERROR 500 An unexpected server error occurred.