Errors

SignumEra uses standard HTTP status codes together with structured JSON error responses.

Error Format

Most API errors use the following format: 

{
    "error": {
        "code": "error_code",
        "message": "Human-readable description."
    }
}

HTTP Status Codes

Status Meaning
400 Malformed or invalid request.
401 Missing, invalid or expired OAuth access token.
403 The authenticated application is not permitted to perform the operation.
404 The requested resource was not found.
409 The request conflicts with the current resource or ceremony state.
413 The uploaded document exceeds the permitted size.
415 Unsupported Content-Type.
422 The request was understood but failed validation.
503 A SignumEra internal service required to complete the operation is temporarily unavailable.

Upload Errors

HTTP Code Description
415 invalid_content_type The upload Content-Type must be application/pdf.
422 missing_pdf The PDF request body is empty.
413 pdf_too_large The PDF exceeds the 50 MiB upload limit.
422 invalid_pdf The request body does not contain a valid PDF document header.
503 upstream_unavailable The document upload service is temporarily unavailable.

Signing Request Errors

HTTP Code Description
422 invalid_idempotency_key A valid Idempotency-Key header is required when creating a signing request.
409 idempotency_key_reused The supplied Idempotency-Key was previously used with a different request payload.
404 signing_request_not_found The signing request could not be found for the current organization or application.
409 signing_request_not_ready The signing request has not reached the state required for the requested operation.
503 upstream_submission_failed A previous attempt to submit the signing request to the signing service failed.
503 upstream_unavailable The signing service is temporarily unavailable.

Participant Errors

HTTP Code Description
403 participant_forbidden The application cannot modify participants for this signing request.
409 participant_conflict Ceremony state or signing sequence prevents the participant from being added.
422 invalid_participant_request The participant request is invalid.

Preparation Errors

HTTP Code Description
403 prepare_forbidden The application cannot prepare this signing request.
409 prepare_conflict The signing request cannot be prepared in its current state.
422 invalid_prepare_request The preparation request is invalid.

Widget Session Errors

HTTP Code Description
403 widget_session_forbidden The application is not authorized to launch this signing request.
409 widget_session_conflict A widget session cannot be created in the current signing state.
422 invalid_widget_session_request The widget launch request is invalid.

Cancellation Errors

HTTP Code Description
409 signing_request_conflict The signing request can no longer be cancelled.
422 invalid_cancellation_request The cancellation request is invalid.

Laravel Validation Errors

Laravel validation failures may return HTTP 422 Unprocessable Entity with field-specific validation information. 

{
    "message": "The given data was invalid.",
    "errors": {
        "external_reference": [
            "The external reference field is required."
        ]
    }
}

Handling Errors

Applications should use the HTTP status code for broad error handling and the SignumEra error code for application-specific behavior.

Do not build application logic by matching the human-readable message, because message text may change without changing the underlying error code.