Error codes. MySign Developer Centre

Format

Error response format.

All API errors follow a consistent JSON structure to help you identify and handle issues programmatically.

Field	Type	Description
error.code	string	Machine-readable error code
error.message	string	Human-readable error description
error.status	integer	HTTP status code
error.details	object	Additional context about the error (optional)

JSON

{
  "error": {
    "code": "INVALID_TEMPLATE",
    "message": "The specified template does not exist or you do not have access to it.",
    "status": 404,
    "details": {
      "template_id": "01JGXYZ123ABC456DEF789"
    }
  }
}

Status codes

HTTP status codes.

The MySign API uses standard HTTP status codes to indicate success or failure.

2xx

Success

The request was successful.

200 OK Request successful

201 Created Resource created successfully

4xx

Client errors

The request contains invalid data or lacks proper authorisation.

400 Bad Request Invalid request parameters

401 Unauthorized Missing or invalid API token

403 Forbidden Valid token but insufficient permissions

404 Not Found Resource does not exist

422 Unprocessable Entity Validation errors

429 Too Many Requests Rate limit exceeded

5xx

Server errors

An error occurred on the MySign server.

500 Internal Server Error Unexpected server error

503 Service Unavailable Temporary service outage

Error codes

API error codes.

MySign-specific error codes to help you identify and resolve issues.

Authentication errors

MISSING_TOKEN

No API token provided in the Authorization header.

401 Unauthorized

INVALID_TOKEN

The provided API token is invalid, expired, or has been revoked.

401 Unauthorized

INSUFFICIENT_PERMISSIONS

Your API token is valid but does not have permission to access this resource.

403 Forbidden

Validation errors

VALIDATION_ERROR

One or more request parameters failed validation. Check the details field for specific field errors.

422 Unprocessable Entity

MISSING_REQUIRED_FIELD

A required field is missing from the request.

400 Bad Request

INVALID_EMAIL

The provided email address is not in a valid format.

422 Unprocessable Entity

INVALID_PHONE

The provided phone number is not in a valid UK format (e.g., +44 7700 900000).

422 Unprocessable Entity

Resource errors

TEMPLATE_NOT_FOUND

The specified template does not exist or you do not have access to it.

404 Not Found

ENVELOPE_NOT_FOUND

The specified envelope does not exist or you do not have access to it.

404 Not Found

ENVELOPE_ALREADY_COMPLETED

Cannot modify an envelope that has already been completed.

400 Bad Request

ENVELOPE_EXPIRED

The envelope has expired and can no longer be signed.

400 Bad Request

Rate limiting

RATE_LIMIT_EXCEEDED

You have exceeded the API rate limit. Please wait before making additional requests. Check the Retry-After header for when to retry.

429 Too Many Requests

Guidance

Error handling best practices.

Follow these guidelines to handle API errors effectively in your application.

Always check the HTTP status code

Use the HTTP status code first to determine the category of error (4xx for client errors, 5xx for server errors).

Parse error codes for specific handling

Use the error.code field to implement specific error handling logic (e.g., redirect to login for INVALID_TOKEN).

Display user-friendly messages

Show the error.message to users, but avoid exposing technical details that could be exploited.

Implement retry logic for server errors

For 5xx errors and rate limiting (429), implement exponential backoff retry logic. Respect the Retry-After header when present.

Log errors for debugging

Always log the full error response (including the details object) to help with troubleshooting.

In practice

Example: error handling.

Here's how to handle errors gracefully in your application:

PHP example

PHP

try {
    $response = $client->post('https://api.mysign.co.uk/api/v1/native/envelopes/create', [
        'headers' => [
            'Authorization' => 'Bearer ' . $apiToken,
            'Content-Type' => 'application/json',
        ],
        'json' => $envelopeData,
    ]);

    $data = json_decode($response->getBody(), true);
    // Handle success...

} catch (GuzzleHttp\Exception\ClientException $e) {
    // 4xx errors (client errors)
    $response = $e->getResponse();
    $errorData = json_decode($response->getBody(), true);

    switch ($errorData['error']['code']) {
        case 'INVALID_TOKEN':
            // Redirect to login or refresh token
            break;
        case 'TEMPLATE_NOT_FOUND':
            // Show user-friendly message
            break;
        case 'VALIDATION_ERROR':
            // Display validation errors
            $errors = $errorData['error']['details'];
            break;
        default:
            // Generic error message
            Log::error('API Error: ' . $errorData['error']['message']);
    }

} catch (GuzzleHttp\Exception\ServerException $e) {
    // 5xx errors (server errors) - implement retry logic
    Log::error('Server error, will retry');
    // Retry with exponential backoff...
}

JavaScript example

JavaScript

try {
  const response = await fetch('https://api.mysign.co.uk/api/v1/native/envelopes/create', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(envelopeData),
  });

  if (!response.ok) {
    const errorData = await response.json();

    // Handle specific error codes
    switch (errorData.error.code) {
      case 'INVALID_TOKEN':
        // Redirect to login
        window.location.href = '/login';
        break;
      case 'VALIDATION_ERROR':
        // Display validation errors to user
        displayValidationErrors(errorData.error.details);
        break;
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        const retryAfter = response.headers.get('Retry-After');
        setTimeout(() => retryRequest(), retryAfter * 1000);
        break;
      default:
        // Generic error
        console.error('API Error:', errorData.error.message);
        showErrorMessage(errorData.error.message);
    }
    return;
  }

  const data = await response.json();
  // Handle success...

} catch (error) {
  // Network error or other unexpected issues
  console.error('Network error:', error);
  showErrorMessage('Unable to connect to MySign API');
}

Error codes.

Error response format.

HTTP status codes.

Success

Client errors

Server errors

API error codes.

Authentication errors

Validation errors

Resource errors

Rate limiting

Error handling best practices.

Example: error handling.

That's the lot.